Index: /trunk/doc/manual/Config.kmk =================================================================== --- /trunk/doc/manual/Config.kmk (revision 82349) +++ /trunk/doc/manual/Config.kmk (revision 82350) @@ -297,7 +297,7 @@ 'Oracle VM VirtualBox'\'' >' \ '' \ - '' \ - '' \ - '' + '' \ + '' \ + '' endif # VBOX_XML_ENTITIES Index: /trunk/doc/manual/en_US/UserManual.xml =================================================================== --- /trunk/doc/manual/en_US/UserManual.xml (revision 82349) +++ /trunk/doc/manual/en_US/UserManual.xml (revision 82350) @@ -9,7 +9,7 @@ - + - &VBOX_PRODUCT; + &VBOX_PRODUCT; User Manual Index: /trunk/doc/manual/en_US/user_AdvancedTopics.xml =================================================================== --- /trunk/doc/manual/en_US/user_AdvancedTopics.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_AdvancedTopics.xml (revision 82350) @@ -30,13 +30,12 @@ - Since Windows NT, Windows has provided a modular system login - subsystem, called Winlogon, which can be customized and extended - by means of so-called GINA (Graphical Identification and - Authentication) modules. With Windows Vista and Windows 7, the - GINA modules were replaced with a new mechanism called - credential providers. The &product-name; Guest Additions for - Windows come with both, a GINA and a credential provider module, - and therefore enable any Windows guest to perform automated - logins. + Windows provides a modular system login subsystem, called + Winlogon, which can be customized and extended by means of + so-called GINA (Graphical Identification and Authentication) + modules. In Windows Vista and later releases, the GINA modules + were replaced with a new mechanism called credential providers. + The &product-name; Guest Additions for Windows come with both, a + GINA and a credential provider module, and therefore enable any + Windows guest to perform automated logins. @@ -44,7 +43,7 @@ To activate the &product-name; GINA or credential provider module, install the Guest Additions using the command line - switch /with_autologon. All the - following manual steps required for installing these modules - will be then done by the installer. + switch . All the following + manual steps required for installing these modules will be then + done by the installer. @@ -52,9 +51,9 @@ To manually install the &product-name; GINA module, extract the Guest Additions as shown in - and copy the - file VBoxGINA.dll to the - Windows SYSTEM32 directory. - Then, in the registry, create the following key with a value of - VBoxGINA.dll: + , and copy the + VBoxGINA.dll file to the Windows + SYSTEM32 directory. In the registry, create + the following key with a value of + VBoxGINA.dll: @@ -64,7 +63,7 @@ The &product-name; GINA module is implemented as a wrapper - around the standard Windows GINA module, - MSGINA.DLL. As a result, it - may not work correctly with third party GINA modules. + around the MSGINA.DLL standard Windows + GINA module. As a result, it might not work correctly with + third-party GINA modules. @@ -73,9 +72,8 @@ To manually install the &product-name; credential provider module, extract the Guest Additions as shown in - and copy - the file VBoxCredProv.dll to - the Windows SYSTEM32 directory. - In the registry, create the following keys: + and copy the + VBoxCredProv.dll file to the Windows + SYSTEM32 directory. In the registry, create + the following keys: @@ -88,12 +86,11 @@ - All default values, the key named - Default, must be set to - VBoxCredProv. - - - - Create a new string named as follows, with a value of - Apartment. + All default values, the key named Default, + must be set to VBoxCredProv. + + + + Create the following string and assign it a value of + Apartment. @@ -105,5 +102,5 @@ -VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST" +$ VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST" @@ -127,6 +124,6 @@ - Depending on the particular variant of the Windows guest, the - following restrictions apply: + Depending on the Windows guest version, the following + restrictions apply: @@ -138,5 +135,5 @@ login subsystem needs to be configured to use the classic login dialog, as the &product-name; GINA module does not - support the XP-style welcome dialog. + support the Windows XP-style welcome dialog. @@ -147,11 +144,11 @@ and Windows 10 guests. The login subsystem does not support the so-called Secure Attention Sequence, - Ctrl+Alt+Del. As a result, - the guest's group policy settings need to be changed to not - use the Secure Attention Sequence. Also, the user name given - is only compared to the true user name, not the user - friendly name. This means that when you rename a user, you - still have to supply the original user name as Windows never - renames user accounts internally. + Ctrl+Alt+Del. As a result, the guest's + group policy settings need to be changed to not use the + Secure Attention Sequence. Also, the user name given is only + compared to the true user name, not the user friendly name. + This means that when you rename a user, you still have to + supply the original user name as Windows never renames user + accounts internally. @@ -163,6 +160,6 @@ Service, formerly known as Terminal Services, is disabled by default. To enable it, create the following - registry key with a DWORD - value of 1. + registry key with a DWORD value of + 1. @@ -177,5 +174,5 @@ -VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1 +$ VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1 @@ -205,44 +202,42 @@ - The pam_vbox.so module itself + The pam_vbox.so module itself does not do an actual verification of the credentials passed to the guest OS. Instead it relies on other - modules such as pam_unix.so or - pam_unix2.so down in the PAM - stack to do the actual validation using the credentials - retrieved by pam_vbox.so. - Therefore pam_vbox.so has to be - on top of the authentication PAM service list. + modules such as pam_unix.so or + pam_unix2.so down in the PAM stack to do + the actual validation using the credentials retrieved by + pam_vbox.so. Therefore + pam_vbox.so has to be on top of the + authentication PAM service list. - The pam_vbox.so module only - supports the auth primitive. - Other primitives such as - account, - session, or - password are not supported. + The pam_vbox.so module only supports the + auth primitive. Other primitives such as + account, session, or + password are not supported. - The pam_vbox.so module is - shipped as part of the Guest Additions but it is not installed - and/or activated on the guest OS by default. In order to install - it, it has to be copied from - /opt/VBoxGuestAdditions-<version>/other/ + The pam_vbox.so module is shipped as part + of the Guest Additions but it is not installed and/or activated + on the guest OS by default. In order to install it, it has to be + copied from + /opt/VBoxGuestAdditions-version/other/ to the security modules directory. This is usually - /lib/security/ on 32-bit Linux - guests or /lib64/security/ on - 64-bit Linux guests. Please refer to your guest OS documentation - for the correct PAM module directory. - - - - For example, to use pam_vbox.so - with a Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) - to log in users automatically with the credentials passed by the - host, configure the guest OS as follows: + /lib/security/ on 32-bit Linux guests or + /lib64/security/ on 64-bit Linux guests. + Please refer to your guest OS documentation for the correct PAM + module directory. + + + + For example, to use pam_vbox.so with a + Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log + in users automatically with the credentials passed by the host, + configure the guest OS as follows: @@ -251,7 +246,7 @@ - Copy the pam_vbox.so module - to the security modules directory. In this case, - /lib/security. + Copy the pam_vbox.so module to the + security modules directory. In this case, + /lib/security. @@ -260,12 +255,11 @@ Edit the PAM configuration file for GDM, found at - /etc/pam.d/gdm. Add the - line auth requisite - pam_vbox.so at the top. Additionally, in - most Linux distributions there is a file called - /etc/pam.d/common-auth. - This file is included in many other services, like the GDM - file mentioned above. There you also have to add the line - auth requisite pam_vbox.so. + /etc/pam.d/gdm. Add the line + auth requisite pam_vbox.so at the top. + Additionally, in most Linux distributions there is a file + called /etc/pam.d/common-auth. This + file is included in many other services, like the GDM file + mentioned above. There you also have to add the line + auth requisite pam_vbox.so. @@ -274,19 +268,17 @@ If authentication against the shadow database using - pam_unix.so or - pam_unix2.so is desired, - the argument try_first_pass - for pam_unix.so or - use_first_pass for - pam_unix2.so is needed in - order to pass the credentials from the &product-name; module - to the shadow database authentication module. For Ubuntu, - this needs to be added to - /etc/pam.d/common-auth, to - the end of the line referencing - pam_unix.so. This argument - tells the PAM module to use credentials already present in - the stack, such as the ones provided by the &product-name; - PAM module. + pam_unix.so or + pam_unix2.so is desired, the argument + try_first_pass for + pam_unix.so or + use_first_pass for + pam_unix2.so is needed in order to pass + the credentials from the &product-name; module to the shadow + database authentication module. For Ubuntu, this needs to be + added to /etc/pam.d/common-auth, to the + end of the line referencing + pam_unix.so. This argument tells the + PAM module to use credentials already present in the stack, + such as the ones provided by the &product-name; PAM module. @@ -303,26 +295,26 @@ To make deployment easier, you can pass the argument - debug right after the - pam_vbox.so statement. Debug - log output will then be recorded using syslog. + debug right after the + pam_vbox.so statement. Debug log output + will then be recorded using syslog. - By default, pam_vbox will not - wait for credentials to arrive from the host. When a login - prompt is shown, for example by GDM/KDM or the text console, - and pam_vbox does not yet have credentials it does not wait - until they arrive. Instead the next module in the PAM stack, - depending on the PAM configuration, will have the chance for - authentication. + By default, pam_vbox does not wait for + credentials to arrive from the host. When a login prompt is + shown, for example by GDM/KDM or the text console, and + pam_vbox does not yet have credentials it + does not wait until they arrive. Instead the next module in + the PAM stack, depending on the PAM configuration, will have + the chance for authentication. - pam_vbox supports various guest - property parameters that are located in - /VirtualBox/GuestAdd/PAM/. - These parameters allow pam_vbox to wait for credentials to be + pam_vbox supports various guest property + parameters that are located in + /VirtualBox/GuestAdd/PAM/. These parameters + allow pam_vbox to wait for credentials to be provided by the host and optionally can show a message while waiting for those. The following guest properties can be set: @@ -333,12 +325,13 @@ - CredsWait: Set to 1 if - pam_vbox should start waiting until credentials arrive from - the host. Until then no other authentication methods such as - manually logging in will be available. If this property is - empty or gets deleted no waiting for credentials will be - performed and pam_vbox will act like before. This property - must be set read-only for the guest - (RDONLYGUEST). + CredsWait: Set to 1 if + pam_vbox should start waiting until + credentials arrive from the host. Until then no other + authentication methods such as manually logging in will be + available. If this property is empty or gets deleted no + waiting for credentials will be performed and + pam_vbox will act like before. This + property must be set read-only for the guest + (RDONLYGUEST). @@ -346,7 +339,7 @@ - CredsWaitAbort: Aborts - waiting for credentials when set to any value. Can be set - from host and the guest. + CredsWaitAbort: Aborts waiting for + credentials when set to any value. Can be set from host and + the guest. @@ -354,13 +347,13 @@ - CredsWaitTimeout: Timeout, - in seconds, to let pam_vbox wait for credentials to arrive. - When no credentials arrive within this timeout, - authentication of pam_vbox will be set to failed and the - next PAM module in chain will be asked. If this property is - not specified, set to 0 or an invalid value, an infinite - timeout will be used. This property must be set read-only - for the guest - (RDONLYGUEST). + CredsWaitTimeout: Timeout, in seconds, to + let pam_vbox wait for credentials to + arrive. When no credentials arrive within this timeout, + authentication of pam_vbox will be set to + failed and the next PAM module in chain will be asked. If + this property is not specified, set to 0 or an invalid + value, an infinite timeout will be used. This property must + be set read-only for the guest + (RDONLYGUEST). @@ -369,6 +362,6 @@ - To customize pam_vbox further there are the following guest - properties: + To customize pam_vbox further there are the + following guest properties: @@ -377,8 +370,8 @@ - CredsMsgWaiting: Custom - message showed while pam_vbox is waiting for credentials - from the host. This property must be set read-only for the - guest (RDONLYGUEST). + CredsMsgWaiting: Custom message showed + while pam_vbox is waiting for credentials from the host. + This property must be set read-only for the guest + (RDONLYGUEST). @@ -386,9 +379,9 @@ - CredsMsgWaitTimeout: Custom - message showed when waiting for credentials by pam_vbox has - timed out. For example, they did not arrive within time. - This property must be set read-only for the guest - (RDONLYGUEST). + CredsMsgWaitTimeout: Custom message + showed when waiting for credentials by + pam_vbox has timed out. For example, they + did not arrive within time. This property must be set + read-only for the guest (RDONLYGUEST). @@ -398,11 +391,10 @@ - If a pam_vbox guest property does not have the correct flag - set (RDONLYGUEST) the + If a pam_vbox guest property does not have + the correct flag set (RDONLYGUEST) the property is ignored and, depending on the property, a default value will be used. This can result in pam_vbox not waiting for credentials. Consult the appropriate syslog file for more - information and use the debug - option. + information and use the debug option. @@ -413,28 +405,29 @@ - &product-name; comes with an own greeter module, named - vbox-greeter. The module can be used with LightDM 1.0.1 or - later. LightDM is the default display manager since Ubuntu - 10.11 and therefore also can be used for automated guest + &product-name; comes with a greeter module, named + vbox-greeter, that can be used with + LightDM. LightDM is the default display manager for Ubuntu + Linux and therefore can also be used for automated guest logins. - vbox-greeter does not need the - pam_vbox module described - above in order to function. It comes with its own - authentication mechanism provided by LightDM. However, to - provide maximum of flexibility both modules can be used - together on the same guest. - - - - As with the pam_vbox module, - vbox-greeter is shipped as part of the Guest Additions but it - is not installed or activated on the guest OS by default. To - install vbox-greeter automatically upon Guest Additions - installation, use the - --with-autologon switch when - starting the VBoxLinuxAdditions.run file: + vbox-greeter does not need the + pam_vbox module described in + in order to function. It comes + with its own authentication mechanism provided by LightDM. + However, to provide maximum flexibility both modules can be + used together on the same guest. + + + + As with the pam_vbox module, + vbox-greeter is shipped as part of the + Guest Additions but it is not installed or activated on the + guest OS by default. To install + vbox-greeter automatically upon Guest + Additions installation, use the + option when starting the + VBoxLinuxAdditions.run file: @@ -442,22 +435,20 @@ - For manual or postponed installation, the - vbox-greeter.desktop file has - to be copied from - /opt/VBoxGuestAdditions-<version>/other/ - to the xgreeters directory - This is usually - /usr/share/xgreeters/. Please - refer to your guest OS documentation for the correct LightDM + For manual or postponed installation, copy the + vbox-greeter.desktop file from + /opt/VBoxGuestAdditions-<version>/other/ + to the xgreeters directory, which is + usually /usr/share/xgreeters/. See your + guest OS documentation for the name of the correct LightDM greeter directory. - The vbox-greeter module itself already was installed by the - &product-name; Guest Additions installer and resides in - /usr/sbin/. To enable - vbox-greeter as the standard greeter module, the file - /etc/lightdm/lightdm.conf - needs to be edited: + The vbox-greeter module is installed by the + &product-name; Guest Additions installer and is located in + /usr/sbin/. To enable + vbox-greeter as the standard greeter + module, edit the file + /etc/lightdm/lightdm.conf as follows: @@ -470,8 +461,8 @@ - The LightDM server needs to be fully restarted in order - for vbox-greeter to be used as the default greeter. As - root, run service lightdm - --full-restart on Ubuntu, or simply + The LightDM server must be fully restarted in order for + vbox-greeter to be used as the + default greeter. As root on Ubuntu, + run service lightdm --full-restart or restart the guest. @@ -480,8 +471,9 @@ - vbox-greeter is independent of the graphical session - chosen by the user, such as Gnome, KDE, or Unity. - However, it requires FLTK 1.3 for representing its own - user interface. + vbox-greeter is independent of the + graphical session you choose, such as Gnome, KDE, or + Unity. However, vbox-greeter does + require FLTK 1.3 or later to implement its own user + interface. @@ -494,12 +486,14 @@ further customize the login experience. For automatically logging in users, the same guest properties apply as for - pam_vbox. See . - - - - In addition to the above mentioned guest properties, - vbox-greeter allows further customization of its user - interface. These special guest properties all reside in - /VirtualBox/GuestAdd/Greeter/: + pam_vbox. See + . + + + + In addition to the previously mentioned guest properties, + vbox-greeter enables you to further + customize its user interface. The following guest properties + are located in the + /VirtualBox/GuestAdd/Greeter/ directory: @@ -508,72 +502,70 @@ - HideRestart: Set to 1 if - vbox-greeter should hide the button to restart the guest. - This property must be set read-only for the guest - (RDONLYGUEST). - - - - - - HideShutdown: Set to 1 if - vbox-greeter should hide the button to shutdown the guest. - This property must be set read-only for the guest - (RDONLYGUEST). - - - - - - BannerPath: Path to a - .PNG file for using it as a banner on the top. The image - size must be 460 x 90 pixels, any bit depth. This property - must be set read-only for the guest - (RDONLYGUEST). - - - - - - UseTheming: Set to 1 for - turning on the following theming options. This property - must be set read-only for the guest - (RDONLYGUEST). - - - - - - Theme/BackgroundColor: - Hexadecimal RRGGBB color for the background. This property - must be set read-only for the guest - (RDONLYGUEST). - - - - - - Theme/LogonDialog/HeaderColor: + HideRestart: Set to 1 if + vbox-greeter should hide the button to + restart the guest. This property must be set read-only for + the guest (RDONLYGUEST). + + + + + + HideShutdown: Set to 1 if + vbox-greeter should hide the button to + shutdown the guest. This property must be set read-only + for the guest (RDONLYGUEST). + + + + + + BannerPath: Path to a + .PNG file to use as a banner image on + the top of the greeter. The image size must be 460 x 90 + pixels, any bit depth. This property must be set read-only + for the guest (RDONLYGUEST). + + + + + + UseTheming: Set to 1 for turning on the + following theming options. This property must be set + read-only for the guest (RDONLYGUEST). + + + + + + Theme/BackgroundColor: Hexadecimal + RRGGBB color for the background. This property must be set + read-only for the guest (RDONLYGUEST). + + + + + + Theme/LogonDialog/HeaderColor: Hexadecimal RRGGBB foreground color for the header text. This property must be set read-only for the guest - (RDONLYGUEST). - - - - - - Theme/LogonDialog/BackgroundColor: + (RDONLYGUEST). + + + + + + Theme/LogonDialog/BackgroundColor: Hexadecimal RRGGBB color for the login dialog background. This property must be set read-only for the guest - (RDONLYGUEST). - - - - - - Theme/LogonDialog/ButtonColor: + (RDONLYGUEST). + + + + + + Theme/LogonDialog/ButtonColor: Hexadecimal RRGGBB background color for the login dialog button. This property must be set read-only for the guest - (RDONLYGUEST). + (RDONLYGUEST). @@ -584,5 +576,6 @@ The same restrictions for the guest properties above apply - as for the ones specified in the pam_vbox section. + as for the ones specified in the pam_vbox + section. @@ -603,13 +596,13 @@ - Beginning with Windows NT 4.0, Microsoft offers a system - preparation tool called Sysprep, to prepare a Windows system for - deployment or redistribution. Whereas Windows 2000 and XP ship - with Sysprep on the installation medium, the tool also is - available for download on the Microsoft web site. In a standard - installation of Windows Vista and 7, Sysprep is already - included. Sysprep mainly consists of an executable called - sysprep.exe which is invoked by - the user to put the Windows installation into preparation mode. + Microsoft offers a system preparation tool called Sysprep, to + prepare a Windows system for deployment or redistribution. Some + Windows releases include Sysprep on the installation medium, but + the tool is also available for download from the Microsoft web + site. In a standard For most Windows versions, Sysprep is + included in a default installation. Sysprep mainly consists of + an executable called sysprep.exe which is + invoked by the user to put the Windows installation into + preparation mode. @@ -620,17 +613,15 @@ for details of how to use this feature with the special identifier - sysprep as the program to - execute, along with the user name - sysprep and password - sysprep for the credentials. - Sysprep then gets launched with the required system rights. + sysprep as the program to execute, along with + the user name sysprep and password + sysprep for the credentials. Sysprep is then + started with the required system rights. - Specifying the location of "sysprep.exe" is - not possible. Instead - the following paths are used, based on the operating system: + Specifying the location of sysprep.exe is + not possible. Instead the + following paths are used, based on the Windows release: @@ -639,13 +630,13 @@ - C:\sysprep\sysprep.exe - for Windows NT 4.0, 2000 and XP - - - - - - %WINDIR%\System32\Sysprep\sysprep.exe - for Windows Vista, 2008 Server and 7 + C:\sysprep\sysprep.exe for Windows XP + and earlier + + + + + + %WINDIR%\System32\sysprep\sysprep.exe + for Windows Vista and later @@ -673,46 +664,41 @@ The &product-name; Guest Additions contain several different - drivers. If for any reason you do not wish to set them all up, - you can install the Guest Additions using the following command: - - - sh ./VBoxLinuxAdditions.run no_setup - - - After this, you will need to at least compile the kernel modules - by running the command as root: - - - rcvboxadd setup - - - You will need to replace lib by - lib64 on some 64bit guests, and on older - guests without the udev service you will need to add the - vboxadd service to the default runlevel to - ensure that the modules get loaded. - - - - To setup the time synchronization service, add the service - vboxadd-service to the default runlevel. To set up the X11 and - OpenGL part of the Guest Additions, run the following command: - - - rcvboxadd-x11 setup - - - You do not need to enable any services for this. - - - - To recompile the guest kernel modules, use this command: - - - rcvboxadd setup - - - After compilation you should reboot your guest to ensure that - the new modules are actually used. + drivers. If you do not want to configure them all, use the + following command to install the Guest Additions: + + +$ sh ./VBoxLinuxAdditions.run no_setup + + + After running this script, run the rcvboxadd + setup command as root to compile + the kernel modules. + + + + On some 64-bit guests, you must replace lib + with lib64. On older guests that do not run + the udev service, you must add the + vboxadd service to the default runlevel to + ensure that the modules are loaded. + + + + To set up the time synchronization service, add the + vboxadd-service service to the default + runlevel. To set up the X11 and OpenGL part of the Guest + Additions, run the rcvboxadd-x11 setup + command. Note that you do not need to enable additional + services. + + + + Use the rcvboxadd setup to recompile the + guest kernel modules. + + + + After compilation, reboot your guest to ensure that the new + modules are loaded. @@ -731,44 +717,10 @@ - The &product-name; Guest Additions include the following drivers - for X.Org versions: - - - - - - - X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o - and vboxmouse_drv_68.o) - - - - - - X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so) - - - - - - X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so) - - - - - - X.Org Server versions 1.3 and later (vboxvideo_drv_13.so - vboxmouse_drv_13.so, and later versions). - - - - - - - By default these drivers can be found in the folowing directory: - - - - /opt/VBoxGuestAdditions-<version>/other/ + The &product-name; Guest Additions includes drivers for X.Org. + By default these drivers are in the following directory: + + + + /opt/VBoxGuestAdditions-version/other/ @@ -780,16 +732,20 @@ For graphics integration to work correctly, the X server must - load the vboxvideo driver. Many recent X server versions look - for it automatically if they see that they are running in - &product-name;. For an optimal user experience the guest kernel - drivers must be loaded and the Guest Additions tool VBoxClient - must be running as a client in the X session. For mouse - integration to work correctly, the guest kernel drivers must be - loaded and in addition, in X servers from X.Org X11R6.8 to - X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver - must be loaded and associated with /dev/mouse or /dev/psaux. In - X.Org server 1.3 or later a driver for a PS/2 mouse must be - loaded and the right vboxmouse driver must be associated with - /dev/vboxguest. + load the vboxvideo driver. Many recent X + server versions look for it automatically if they see that they + are running in &product-name;. For an optimal user experience, + the guest kernel drivers must be loaded and the Guest Additions + tool VBoxClient must be running as a client + in the X session. + + + + For mouse integration to work correctly, the guest kernel + drivers must be loaded. In addition, for legacy X servers the + correct vboxmouse driver must be loaded and + associated with /dev/mouse or + /dev/psaux. For most guests, a driver for a + PS/2 mouse must be loaded and the correct vboxmouse driver must + be associated with /dev/vboxguest. @@ -799,22 +755,21 @@ virtual video memory allocated to the virtual machine, minus a small amount used by the guest driver, as described in - . The driver will offer - a range of standard modes at least up to the default guest - resolution for all active guest monitors. In X.Org Server 1.3 - and later the default mode can be changed by setting the output - property VBOX_MODE to "<width>x<height>" for any - guest monitor. When VBoxClient and the kernel drivers are active - this is done automatically when the host requests a mode change. - The driver for older versions can only receive new modes by - querying the host for requests at regular intervals. - - - - With X Servers before version 1.3, you can also add your own - modes to the X server configuration file. You simply need to add - them to the "Modes" list in the "Display" subsection of the - "Screen" section. For example, the following section has a - custom 2048x800 resolution mode added: + . The driver will offer a + range of standard modes at least up to the default guest + resolution for all active guest monitors. The default mode can + be changed by setting the output property VBOX_MODE to + "<width>x<height>" for any guest monitor. When + VBoxClient and the kernel drivers are active this is done + automatically when the host requests a mode change. The driver + for older versions can only receive new modes by querying the + host for requests at regular intervals. + + + + With legacy X Servers before version 1.3, you can also add your + own modes to the X server configuration file. Add them to the + "Modes" list in the "Display" subsection of the "Screen" + section. For example, the following section has a custom + 2048x800 resolution mode added: @@ -864,23 +819,22 @@ -VBoxManage modifyvm "VM name" --cpuhotplug on - - - The --cpus option is used to - specify the maximum number of CPUs that the virtual machine can - have: - - -VBoxManage modifyvm "VM name" --cpus 8 +$ VBoxManage modifyvm VM-name --cpuhotplug on + + + The option is used to specify the maximum + number of CPUs that the virtual machine can have: + + +$ VBoxManage modifyvm VM-name --cpus 8 When the VM is off, you can then add and remove virtual CPUs with - the modifyvm --plugcpu and - --unplugcpu subcommands, which + the VBoxManage modifyvm --plugcpu and + VBoxManage modifyvm --unplugcpu commands, which take the number of the virtual CPU as a parameter, as follows: -VBoxManage modifyvm "VM name" --plugcpu 3 -VBoxManage modifyvm "VM name" --unplugcpu 3 +$ VBoxManage modifyvm VM-name --plugcpu 3 +$ VBoxManage modifyvm VM-name --unplugcpu 3 @@ -890,16 +844,15 @@ While the VM is running, CPUs can be added and removed with the - controlvm plugcpu and - unplugcpu commands instead, as - follows: - - -VBoxManage controlvm "VM name" plugcpu 3 -VBoxManage controlvm "VM name" unplugcpu 3 + VBoxManage controlvm plugcpu and + VBoxManage controlvm unplugcpu commands + instead, as follows: + + +$ VBoxManage controlvm VM-name plugcpu 3 +$ VBoxManage controlvm VM-name unplugcpu 3 See and - for details. + for details. @@ -918,9 +871,9 @@ -echo 1 > /sys/devices/system/cpu/cpu<id>/online +$ echo 1 > /sys/devices/system/cpu/cpu<id>/online - + @@ -1118,10 +1067,10 @@ - &product-name; 4.3 includes an experimental feature which - enables a guest to use a host webcam. This complements the - general USB passthrough support which was the typical way of - using host webcams in earlier versions. The webcam passthrough - support can handle non-USB video sources in theory, but this is - completely untested. + &product-name; includes a feature called webcam + passthrough, which enables a guest to use a host + webcam. This complements the general USB passthrough support + which was the typical way of using host webcams in legacy + releases. The webcam passthrough support can handle non-USB + video sources in theory, but this is completely untested. @@ -1130,6 +1079,5 @@ The webcam passthrough module is shipped as part of the &product-name; extension pack, which must be installed - separately. See . + separately. See . @@ -1158,5 +1106,5 @@ -VBoxManage list webcams +$ VBoxManage list webcams @@ -1180,5 +1128,5 @@ -VBoxManage controlvm "VM name" webcam attach [host_path|alias [settings]] +VBoxManage controlvm VM name webcam attach [host_path|alias [settings]] @@ -1187,9 +1135,8 @@ - The settings parameter is a - string - Setting1=Value1;Setting2=Value2, - which enables you to configure the emulated webcam device. - The following settings are supported: + The settings parameter is a string + Setting1=Value1;Setting2=Value2, which + enables you to configure the emulated webcam device. The + following settings are supported: @@ -1198,10 +1145,10 @@ - MaxFramerate: The - highest rate at which video frames are sent to the - guest. A higher frame rate requires more CPU power. - Therefore sometimes it is useful to set a lower limit. - Default is no limit and allow the guest to use all frame - rates supported by the host webcam. + MaxFramerate: The highest rate at + which video frames are sent to the guest. A higher frame + rate requires more CPU power. Therefore sometimes it is + useful to set a lower limit. Default is no limit and + allow the guest to use all frame rates supported by the + host webcam. @@ -1209,12 +1156,11 @@ - MaxPayloadTransferSize: - How many bytes the emulated webcam can send to the guest - at a time. Default value is 3060 bytes, which is used by - some webcams. Higher values can slightly reduce CPU - load, if the guest is able to use larger buffers. - However, a high - MaxPayloadTransferSize - might be not supported by some guests. + MaxPayloadTransferSize: How many + bytes the emulated webcam can send to the guest at a + time. Default value is 3060 bytes, which is used by some + webcams. Higher values can slightly reduce CPU load, if + the guest is able to use larger buffers. However, a high + MaxPayloadTransferSize might be not + supported by some guests. @@ -1228,5 +1174,5 @@ -VBoxManage controlvm "VM name" webcam detach [host_path|alias] +VBoxManage controlvm VM-name webcam detach [host_path|alias] @@ -1236,5 +1182,5 @@ -VBoxManage controlvm "VM name" webcam list +VBoxManage controlvm VM-name webcam list @@ -1265,5 +1211,5 @@ - OS X version 10.9 or later is required. + Mac OS X version 10.9 or later is required. @@ -1271,6 +1217,7 @@ When the webcam device is detached from the host, the emulated webcam device remains attached to the guest and must be manually - detached using the VBoxManage controlvm "VM - name" webcam detach command. + detached using the VBoxManage controlvm + VM-name webcam detach + command. @@ -1285,14 +1232,14 @@ device is automatically detached from the guest only if the webcam is streaming video. If the emulated webcam is inactive it - should be manually detached using the VBoxManage - controlvm "VM name" webcam detach command. - - - - Aliases .0 and - .1 are mapped to - /dev/video0, alias - .2 is mapped to - /dev/video1 and so forth. + should be manually detached using the VBoxManage + controlvm VM-name webcam + detach command. + + + + Aliases .0 and .1 are + mapped to /dev/video0, alias + .2 is mapped to + /dev/video1 and so forth. @@ -1321,6 +1268,6 @@ Additional video modes can be configured for each VM using the extra data facility. The extra data key is called - CustomVideoMode<x> with - x being a number from 1 to 16. + CustomVideoModex + with x being a number from 1 to 16. Please note that modes will be read from 1 until either the following number is not defined or 16 is reached. The following @@ -1329,11 +1276,11 @@ -VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16" +$ VBoxManage setextradata VM-name "CustomVideoMode1" "1400x1050x16" The VESA mode IDs for custom video modes start at - 0x160. In order to use the - above defined custom video mode, the following command line has - to be supplied to Linux: + 0x160. In order to use the above defined + custom video mode, the following command line has to be supplied + to Linux: @@ -1362,27 +1309,35 @@ seamless mode or sending a video mode hint using VBoxManage. This behavior is what most users - will want, but if you have different needs, it is possible to - change it by issuing one of the following commands from the - command line: - + will want, but if you have different needs, you can change it by + issuing one of the following commands from the command line: + + + + + + + Remove all limits on guest resolutions. + VBoxManage setextradata global GUI/MaxGuestResolution any - - - will remove all limits on guest resolutions. - - -VBoxManage setextradata global GUI/MaxGuestResolution >width,height< - - - manually specifies a maximum resolution. - + + + + + Manually specify a maximum resolution. + + +VBoxManage setextradata global GUI/MaxGuestResolution widthxheight + + + + + Restore the default settings to all guest VMs. + VBoxManage setextradata global GUI/MaxGuestResolution auto - - - restores the default settings. Note that these settings apply - globally to all guest systems, not just to a single machine. - + + + @@ -1410,9 +1365,9 @@ to access its virtual hard disk without going through the host OS file system. The actual performance difference for image - files vs. raw disk varies greatly depending on the overhead of - the host file system, whether dynamically growing images are - used, and on host OS caching strategies. The caching indirectly - also affects other aspects such as failure behavior. For - example, whether the virtual disk contains all data written + files compared to raw disk varies greatly depending on the + overhead of the host file system, whether dynamically growing + images are used, and on host OS caching strategies. The caching + indirectly also affects other aspects such as failure behavior. + For example, whether the virtual disk contains all data written before a host OS crash. Consult your host OS documentation for details on this. @@ -1466,22 +1421,21 @@ -VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk - -rawdisk /dev/sda - - - This creates the image - /path/to/file.vmdk, which - must be an absolute path. All data will be read and written - from /dev/sda. +$ VBoxManage internalcommands createrawvmdk -filename \ +/path/to/file.vmdk -rawdisk /dev/sda + + + This creates the + /path-to-file.vmdk + file image that must be an absolute path. All data is read and + written from /dev/sda. On a Windows host, instead of the above device specification, - for example use - \\.\PhysicalDrive0. On a Mac - OS X host, instead of the above device specification use for - example /dev/disk1. Note that - on OS X you can only get access to an entire disk if no volume - is mounted from it. + for example use \\.\PhysicalDrive0. On a + Mac OS X host, instead of the above device specification use + for example /dev/disk1. Note that on Mac + OS X you can only get access to an entire disk if no volume is + mounted from it. @@ -1490,6 +1444,6 @@ device. Read/write access is also later needed when using the image from a virtual machine. On some host platforms, such as - Windows Vista and later, raw disk access may be restricted and - not permitted by the host OS in some situations. + Windows, raw disk access may be restricted and not permitted + by the host OS in some situations. @@ -1500,5 +1454,5 @@ -VBoxManage storageattach WindowsXP --storagectl "IDE Controller" +$ VBoxManage storageattach WindowsXP --storagectl "IDE Controller" \ --port 0 --device 0 --type hdd --medium /path/to/file.vmdk @@ -1534,16 +1488,15 @@ -VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk - -rawdisk /dev/sda -partitions 1,5 +$ VBoxManage internalcommands createrawvmdk -filename \ +/path/to/file.vmdk -rawdisk /dev/sda -partitions 1,5 The command is identical to the one for full hard disk access, - except for the additional - -partitions parameter. This - example would create the image - /path/to/file.vmdk, which - must be absolute, and partitions 1 and 5 of - /dev/sda would be made - accessible to the guest. + except for the additional + parameter. This example would create the image + /path-to-file.vmdk, + which must be absolute, and partitions 1 and 5 of + /dev/sda would be made accessible to the + guest. @@ -1557,11 +1510,10 @@ On a Windows host, instead of the above device specification, - use for example - \\.\PhysicalDrive0. On a Mac - OS X host, instead of the above device specification use - /dev/disk1, for example. Note - that on OS X you can only use partitions which are not - mounted. Eject the respective volume first. Partition numbers - are the same on Linux, Windows, and Mac OS X hosts. + use for example \\.\PhysicalDrive0. On a + Mac OS X host, instead of the above device specification use + /dev/disk1, for example. Note that on OS + X you can only use partitions which are not mounted. Eject the + respective volume first. Partition numbers are the same on + Linux, Windows, and Mac OS X hosts. @@ -1571,5 +1523,5 @@ -VBoxManage internalcommands listpartitions -rawdisk /dev/sda +$ VBoxManage internalcommands listpartitions -rawdisk /dev/sda @@ -1596,16 +1548,16 @@ -VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk - -rawdisk /dev/sda -partitions 1,5 -relative +$ VBoxManage internalcommands createrawvmdk -filename \ +/path/to/file.vmdk -rawdisk /dev/sda -partitions 1,5 -relative When used from a virtual machine, the image will then refer not to the entire disk, but only to the individual partitions. - In this example, /dev/sda1 - and /dev/sda5. As a - consequence, read/write access is only required for the - affected partitions, not for the entire disk. During creation - however, read-only access to the entire disk is required to - obtain the partitioning information. + In this example, /dev/sda1 and + /dev/sda5. As a consequence, read/write + access is only required for the affected partitions, not for + the entire disk. During creation however, read-only access to + the entire disk is required to obtain the partitioning + information. @@ -1616,13 +1568,13 @@ This enables for example the guest to boot directly to Windows, while the host boots Linux from the "same" disk. For - this purpose the -mbr - parameter is provided. It specifies a file name from which to - take the MBR code. The partition table is not modified at all, - so a MBR file from a system with totally different - partitioning can be used. An example of this is: - - -VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk - -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr + this purpose the option is provided. It + specifies a file name from which to take the MBR code. The + partition table is not modified at all, so a MBR file from a + system with totally different partitioning can be used. An + example of this is: + + +$ VBoxManage internalcommands createrawvmdk -filename +/path/to/file.vmdk -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr @@ -1651,10 +1603,10 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model" @@ -1671,18 +1623,18 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model" - - - For hard disks it is also possible to mark the drive as having a - non-rotational medium with: - - -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model" + + + For hard disks, you can mark the drive as having a + non-rotational medium by using the following command: + + +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1" @@ -1691,10 +1643,10 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor" +VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product" +VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision" @@ -1731,21 +1683,29 @@ -VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Trusted 1 -VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f -VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1 -VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0 -VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet -VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet -VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2 -VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1 +$ VBoxManage setextradata VM-name \ +VBoxInternal/Devices/IntNetIP/0/Trusted 1 +$ VBoxManage setextradata VM-name \ +VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f +$ VBoxManage setextradata VM-name \ +VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1 +$ VBoxManage setextradata VM-name \ +VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0 +$ VBoxManage setextradata VM-name \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet +$ VBoxManage setextradata VM-name \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet +$ VBoxManage setextradata VM-name \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2 +$ VBoxManage setextradata VM-name \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1 Finally the iSCSI disk must be attached with the - --intnet option to tell the - iSCSI initiator to use internal networking, as follows: - - -VBoxManage storageattach ... --medium iscsi ---server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet + option to tell the iSCSI initiator to + use internal networking, as follows: + + +$ VBoxManage storageattach ... --medium iscsi --server 10.0.9.30 \ +--target iqn.2008-12.com.sun:sampletarget --intnet @@ -1767,66 +1727,4 @@ - - - Legacy Commands for Using Serial Ports - - - In legacy releases, &product-name; provided support for virtual - serial ports. This was rather complicated to set up, requiring a - sequence of VBoxManage setextradata statements. - That method of setting up serial ports is no longer necessary and - deprecated. To set up virtual serial ports, - use the methods described in . - - - - - For backwards compatibility, the legacy - setextradata statements, whose - description is retained below from the old version of the - manual, take precedence over the new way of - configuring serial ports. As a result, if configuring serial - ports the new way does not work, make sure the VM in question - does not have old configuration data such as below still active. - - - - - The legacy sequence of configuring a serial port used the - following commands: - - -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/serial/0/Config/IRQ" 4 -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/serial/0/Config/IOBase" 0x3f8 -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/serial/0/LUN#0/Driver" Char -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Driver" NamedPipe -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/Location" "\\.\pipe\vboxCOM1" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/IsServer" 1 - - - This sets up a serial port in the guest with the default settings - for COM1 (IRQ 4, I/O address 0x3f8) and the - Location setting assumes that - this configuration is used on a Windows host, because the Windows - named pipe syntax is used. Keep in mind that on Windows hosts a - named pipe must always start with - \\.\pipe\. On Linux the same - configuration settings apply, except that the path name for the - Location can be chosen more - freely. Local domain sockets can be placed anywhere, provided the - user running &product-name; has the permission to create a new - file in the directory. The final command above defines that - &product-name; acts as a server. It creates the named pipe itself - instead of connecting to an already existing one. - - - - @@ -1839,13 +1737,12 @@ In NAT mode, the guest network interface is assigned to the IPv4 - range 10.0.x.0/24 by default - where x corresponds to the + range 10.0.x.0/24 + by default where x corresponds to the instance of the NAT interface +2. So - x is 2 when there is only one - NAT instance active. In that case the guest is assigned to the - address 10.0.2.15, the gateway - is set to 10.0.2.2 and the name - server can be found at - 10.0.2.3. + x is 2 when there is only one NAT + instance active. In that case the guest is assigned to the + address 10.0.2.15, the gateway is set to + 10.0.2.2 and the name server can be found at + 10.0.2.3. @@ -1855,14 +1752,15 @@ -VBoxManage modifyvm "VM name" --natnet1 "192.168/16" +$ VBoxManage modifyvm VM-name \ +--natnet1 "192.168/16" This command would reserve the network addresses from - 192.168.0.0 to - 192.168.254.254 for the first - NAT network instance of "VM name". The guest IP would be - assigned to 192.168.0.15 and - the default gateway could be found at - 192.168.0.2. + 192.168.0.0 to + 192.168.254.254 for the first NAT network + instance of VM-name The guest IP + would be assigned to 192.168.0.15 and the + default gateway could be found at + 192.168.0.2. @@ -1881,6 +1779,8 @@ -VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2 -VBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe +$ VBoxManage modifyvm VM-name \ +--nattftpserver1 10.0.2.2 +$ VBoxManage modifyvm VM-name \ +--nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe @@ -1893,12 +1793,13 @@ The &product-name; NAT stack performance is often determined by its interaction with the host's TCP/IP stack and the size of - several buffers, SO_RCVBUF and - SO_SNDBUF. For certain setups - users might want to adjust the buffer size for a better - performance. This can by achieved using the following commands, - where values are in kilobytes and can range from 8 to 1024: - - -VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0 + several buffers, SO_RCVBUF and + SO_SNDBUF. For certain setups users might + want to adjust the buffer size for a better performance. This + can by achieved using the following commands, where values are + in kilobytes and can range from 8 to 1024: + + +$ VBoxManage modifyvm VM-name \ +--natsettings1 16000,128,128,0,0 @@ -1932,5 +1833,6 @@ -VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2" +$ VBoxManage modifyvm VM-name \ +--natbindip1 "10.45.0.2" @@ -1956,5 +1858,5 @@ -VBoxManage modifyvm "VM name" --natdnsproxy1 on +$ VBoxManage modifyvm VM-name --natdnsproxy1 on @@ -1973,5 +1875,5 @@ -VBoxManage modifyvm "VM name" --natdnshostresolver1 on +$ VBoxManage modifyvm VM-name --natdnshostresolver1 on @@ -2000,10 +1902,11 @@ -VBoxManage setextradata "VM name" \ - "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ - <unique rule name of interception rule>/HostIP" <IPv4> -VBoxManage setextradata "VM name" \ - "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ - <unique rule name>/HostName" <name of host> +VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +unique-rule-name-of-interception-rule/HostIP" IPv4 + +VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +unique-rule-name/HostName" hostname @@ -2012,14 +1915,16 @@ -VBoxManage setextradata "VM name" \ - "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ - <unique rule name>/HostIP" <IPv4> -VBoxManage setextradata "VM name" \ - "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ - <unique rule name>/HostNamePattern" <hostpattern> - - - The host pattern may include "|", "?" and - "*". +VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +unique-rule-name/HostIP" IPv4 + +VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +unique-rule-name/HostNamePattern" hostpattern + + + The host name pattern can include the following wildcard + characters: pipe (|), question mark + (?), and asterisk (*). @@ -2030,10 +1935,8 @@ -VBoxManage setextradata "VM name" \ - "VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ - all_blocked_site/HostIP" 127.0.0.1 -VBoxManage setextradata "VM name" \ - "VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ - all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostIP" 127.0.0.1 +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org" @@ -2056,12 +1959,12 @@ the most protocols like SSH, FTP and so on. Though some protocols might need a more transparent behavior or may depend - on the real port number the packet was sent from. It is possible - to change the NAT mode using the VBoxManage - frontend with the following commands: - - -VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly - -VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports + on the real port number the packet was sent from. You can change + the NAT mode by using the following commands: + + +$ VBoxManage modifyvm VM-name \ +--nataliasmode1 proxyonly + +$ VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports @@ -2083,7 +1986,6 @@ for a specific VM. Use the following commands to configure the DMI BIOS information. In case your VM is configured to use EFI - firmware you need to replace - pcbios by - efi in the keys. + firmware you need to replace pcbios by + efi in the keys. @@ -2095,18 +1997,18 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1 -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2 -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3 -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4 +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1 +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2 +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3 +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4 @@ -2116,19 +2018,19 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid" - "9852bf98-b83c-49db-a8de-182c42c7226b" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid" \ +"9852bf98-b83c-49db-a8de-182c42c7226b" @@ -2138,18 +2040,18 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor" "Board Vendor" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct" "Board Product" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion" "Board Version" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial" "Board Serial" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag" "Board Tag" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass" "Board Location" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType" 10 +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor" "Board Vendor" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct" "Board Product" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion" "Board Version" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial" "Board Serial" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag" "Board Tag" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass" "Board Location" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType" 10 @@ -2159,14 +2061,14 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor" "Chassis Vendor" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiChassisType" 3 -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion" "Chassis Version" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial" "Chassis Serial" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag" "Chassis Tag" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor" "Chassis Vendor" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisType" 3 +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion" "Chassis Version" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial" "Chassis Serial" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag" "Chassis Tag" @@ -2176,8 +2078,8 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer" "GenuineIntel" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion" "Pentium(R) III" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer" "GenuineIntel" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion" "Pentium(R) III" @@ -2187,8 +2089,8 @@ -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer" "vboxVer_1.2.3" -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev" "vboxRev_12345" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer" "vboxVer_1.2.3" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev" "vboxRev_12345" @@ -2198,5 +2100,5 @@ If a DMI string is not set, the default value of &product-name; is used. To set an empty string use - "<EMPTY>". + "<EMPTY>". @@ -2206,12 +2108,12 @@ strings. If such a string is a valid number, the parameter is treated as number and the VM will most probably refuse to start - with an VERR_CFGM_NOT_STRING - error. In that case, use - "string:<value>". For + with an VERR_CFGM_NOT_STRING error. In that + case, use + "string:value". For example: -VBoxManage setextradata "VM name" - "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234" +$ VBoxManage setextradata VM-name \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234" @@ -2222,5 +2124,5 @@ -dmidecode -t0 +$ dmidecode -t0 @@ -2228,5 +2130,5 @@ -dmidecode -t1 +$ dmidecode -t1 @@ -2237,12 +2139,13 @@ - &product-name; can be configured to present up to four custom ACPI - tables to the guest. A command such as the following can be used - to configure custom ACPI tables. Note that CustomTable1, - CustomTable2, and CustomTable3 are available in addition to - CustomTable0. - - -VBoxManage setextradata "VM name" + You can configure &product-name; to present up to four custom ACPI + tables to the guest. Use a command such as the following to + configure custom ACPI tables. Note that + CustomTable1, CustomTable2, + and CustomTable3 are available in addition to + CustomTable0. + + +$ VBoxManage setextradata VM-name \ "VBoxInternal/Devices/acpi/0/Config/CustomTable0" "/path/to/table.bin" @@ -2252,5 +2155,5 @@ 8 and later guests. On Linux hosts, one of the system's ACPI tables can be read from - /sys/firmware/acpi/tables/. + /sys/firmware/acpi/tables/. @@ -2283,5 +2186,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1 +$ VBoxManage setextradata VM-name "VBoxInternal/TM/TSCTiedToExecution" 1 @@ -2289,5 +2192,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" +$ VBoxManage setextradata VM-name "VBoxInternal/TM/TSCTiedToExecution" @@ -2311,5 +2214,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200 +$ VBoxManage setextradata VM-name "VBoxInternal/TM/WarpDrivePercentage" 200 @@ -2317,5 +2220,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50 +$ VBoxManage setextradata VM-name "VBoxInternal/TM/WarpDrivePercentage" 50 @@ -2347,9 +2250,8 @@ -VBoxManage guestproperty set "VM name" "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE - - - where PARAMETER is one of the - following: +$ VBoxManage guestproperty set VM-name "/VirtualBox/GuestAdd/VBoxService/property" value + + + property is one of the following: @@ -2358,5 +2260,5 @@ - --timesync-interval + @@ -2371,5 +2273,5 @@ - --timesync-min-adjust + @@ -2385,5 +2287,5 @@ - --timesync-latency-factor + @@ -2408,5 +2310,5 @@ - --timesync-max-latency + @@ -2421,5 +2323,5 @@ - --timesync-set-threshold + @@ -2435,5 +2337,5 @@ - --timesync-set-start + @@ -2447,6 +2349,5 @@ - --timesync-set-on-restore - 0|1 + @@ -2481,5 +2382,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1 +$ VBoxManage setextradata VM-name "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1 @@ -2490,11 +2391,11 @@ Installing the Alternate Bridged Networking Driver on Oracle Solaris 11 - hosts + Hosts &product-name; includes a network filter driver that utilizes Oracle Solaris 11's Crossbow functionality. By default, this new - driver is installed for Oracle Solaris 11 hosts, builds 159 and - above, that have support for it. + driver is installed for Oracle Solaris 11 hosts that have support + for it. @@ -2505,5 +2406,5 @@ -touch /etc/vboxinst_vboxflt +$ touch /etc/vboxinst_vboxflt @@ -2513,5 +2414,5 @@ -touch /etc/vboxinst_vboxbow +$ touch /etc/vboxinst_vboxbow @@ -2520,5 +2421,5 @@ -modinfo | grep vbox +$ modinfo | grep vbox @@ -2538,5 +2439,5 @@ for configuring VMs over VLANs. An &product-name; VNIC template is a VNIC whose name starts with - vboxvnic_template. The string is + vboxvnic_template. The string is case-sensitive. @@ -2554,12 +2455,12 @@ -dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0 - - - This will create a temporary VNIC template over interface "nge0" - with the VLAN ID 23. To create VNIC templates that are persistent - across host reboots, skip the -t - parameter in the above command. You may check the current state of - links using the following command: +# dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0 + + + This will create a temporary VNIC template over interface + nge0 with the VLAN ID 23. To create VNIC + templates that are persistent across host reboots, skip the + parameter in the above command. You may check + the current state of links using the following command: @@ -2576,6 +2477,6 @@ Once the VNIC template is created, any VMs that need to be on VLAN - 23 over the interface nge0 can be - configured to bridge using this VNIC template. + 23 over the interface nge0 can be configured to + bridge using this VNIC template. @@ -2590,8 +2491,7 @@ VNIC templates can be created with additional properties such as - bandwidth limits, CPU fanout etc. Refer to your Oracle Solaris - network documentation on how to accomplish this. These additional - properties, if any, are also applied to VMs which bridge using the - VNIC template. + bandwidth limits and CPU fanout. Refer to your Oracle Solaris + network documentation for details. The additional properties are + also applied to VMs which bridge using the VNIC template. @@ -2615,5 +2515,5 @@ -ifconfig vboxnet0 unplumb +# ifconfig vboxnet0 unplumb @@ -2623,11 +2523,10 @@ -rem_drv vboxnet +# rem_drv vboxnet Edit the file - /platform/i86pc/kernel/drv/vboxnet.conf - and add a line for the new interface we want to add as shown - below: + /platform/i86pc/kernel/drv/vboxnet.conf and + add a line for the new interface we want to add as shown below: @@ -2645,5 +2544,5 @@ -add_drv vboxnet +# add_drv vboxnet @@ -2653,5 +2552,5 @@ -dladm show-phys +$ dladm show-phys LINK MEDIA STATE SPEED DUPLEX DEVICE net0 Ethernet up 100 full e1000g0 @@ -2665,13 +2564,13 @@ -dladm rename-link net2 vboxnet1 - - - Now plumb all the interfaces using ifconfig - vboxnetX plumb, where 'X' would be 1 in this - case. Once the interface is plumbed, it may be configured like any - other network interface. Refer to the - ifconfig documentation for - further details. +# dladm rename-link net2 vboxnet1 + + + Now plumb all the interfaces using ifconfig + vboxnetX plumb, where + X would be 1 in this case. Once the + interface is plumbed, it may be configured like any other network + interface. Refer to the ifconfig documentation + for further details. @@ -2679,10 +2578,9 @@ To make the settings for the newly added interfaces persistent across reboots, you will need to edit the files - /etc/inet/netmasks, and if you - are using NWAM /etc/nwam/llp and - add the appropriate entries to set the netmask and static IP for - each of those interfaces. The &product-name; installer only - updates these configuration files for the one "vboxnet0" interface - it creates by default. + /etc/inet/netmasks, and if you are using NWAM + /etc/nwam/llp and add the appropriate entries + to set the netmask and static IP for each of those interfaces. The + &product-name; installer only updates these configuration files + for the one "vboxnet0" interface it creates by default. @@ -2704,5 +2602,5 @@ -VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1 +$ VBoxManage setextradata VM-name VBoxInternal2/CoreDumpEnabled 1 @@ -2711,5 +2609,5 @@ -VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir <path-to-directory> +$ VBoxManage setextradata VM-name VBoxInternal2/CoreDumpDir path-to-directory @@ -2729,6 +2627,6 @@ -VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1 -VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1 +$ VBoxManage setextradata VM-name VBoxInternal2/CoreDumpReplaceSystemDump 1 +$ VBoxManage setextradata VM-name VBoxInternal2/CoreDumpLive 1 @@ -2738,27 +2636,24 @@ - Setting CoreDumpReplaceSystemDump - sets up the VM to override the host's core dumping mechanism and - in the event of any crash only the &product-name; CoreDumper would - produce the core file. - - - - Setting CoreDumpLive sets up the - VM to produce cores whenever the VM process receives a - SIGUSR2 signal. After producing - the core file, the VM will not be terminated and will continue to - run. You can thus take cores of the VM process using the following - command: - - -kill -s SIGUSR2 <VM-process-id> - - - Core files produced by the &product-name; CoreDumper are of the - form - core.vb.<ProcessName>.<ProcessID>, - for example - core.vb.VBoxHeadless.11321. + Setting CoreDumpReplaceSystemDump sets up the + VM to override the host's core dumping mechanism and in the event + of any crash only the &product-name; CoreDumper would produce the + core file. + + + + Setting CoreDumpLive sets up the VM to produce + cores whenever the VM process receives a + SIGUSR2 signal. After producing the core file, + the VM will not be terminated and will continue to run. You can + thus take cores of the VM process using the following command: + + +$ kill -s SIGUSR2 VM-process-id + + + The &product-name; CoreDumper creates core files of the form + core.vb.process-name.process-ID + such as core.vb.VBoxHeadless.11321. @@ -2793,5 +2688,5 @@ -VBoxManage setproperty hwvirtexclusive off +$ VBoxManage setproperty hwvirtexclusive off @@ -2818,9 +2713,9 @@ -VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...] - - - where OPTION is one of the - following keywords: +VBoxManage setextradata global GUI/Customizations property[,property ...] + + + property is one of the following + properties: @@ -2829,5 +2724,5 @@ - noSelector + noSelector @@ -2843,5 +2738,5 @@ - noMenuBar + noMenuBar @@ -2855,5 +2750,5 @@ - noStatusBar + noStatusBar @@ -2872,5 +2767,5 @@ -VBoxManage setextradata global GUI/Customizations +$ VBoxManage setextradata global GUI/Customizations @@ -2886,8 +2781,8 @@ -VBoxManage setextradata "VM name" SETTING true - - - where SETTING can be: +$ VBoxManage setextradata VM-name property true + + + property can be any of the following: @@ -2896,5 +2791,5 @@ - GUI/HideDetails + GUI/HideDetails @@ -2910,5 +2805,5 @@ - GUI/PreventReconfiguration + GUI/PreventReconfiguration @@ -2924,5 +2819,5 @@ - GUI/PreventSnapshotOperations + GUI/PreventSnapshotOperations @@ -2937,5 +2832,5 @@ - GUI/HideFromManager + GUI/HideFromManager @@ -2949,5 +2844,5 @@ - GUI/PreventApplicationUpdate + GUI/PreventApplicationUpdate @@ -2963,7 +2858,7 @@ - Please note that these settings would not prevent the user from - reconfiguring the VM by using VBoxManage - modifyvm. + Note that these settings do not prevent the user from + reconfiguring the VM by using the VBoxManage + modifyvm command. @@ -2979,9 +2874,8 @@ -VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages OPTION[,OPTION...] - - - where OPTION is one of the - following keywords: +$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages property[,property...] + + + property is one of the following: @@ -2990,5 +2884,5 @@ - General + General @@ -3003,5 +2897,5 @@ - Input + Input @@ -3016,5 +2910,5 @@ - Update + Update @@ -3029,5 +2923,5 @@ - Language + Language @@ -3042,5 +2936,5 @@ - Display + Display @@ -3055,5 +2949,5 @@ - Network + Network @@ -3068,5 +2962,5 @@ - Extensions + Extensions @@ -3081,5 +2975,5 @@ - Proxy + Proxy @@ -3095,9 +2989,10 @@ - This is a global setting. Any combination of the above is - allowed. To restore the default behavior, use - - -VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages + This is a global setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + + +$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages @@ -3115,6 +3010,6 @@ - where OPTION is one of the - following keywords: + where OPTION is one of the following + keywords: @@ -3123,5 +3018,5 @@ - All + All @@ -3135,17 +3030,19 @@ - Application - - - - - Do not show Application/File menu in the VM window. - - - - - - - Machine + Application + + + + + Do not show + Application/File menu in + the VM window. + + + + + + + Machine @@ -3160,5 +3057,5 @@ - View + View @@ -3173,17 +3070,18 @@ - Input - - - - - Do not show Input menu in the VM window. - - - - - - - Devices + Input + + + + + Do not show Input menu in + the VM window. + + + + + + + Devices @@ -3198,5 +3096,5 @@ - Help + Help @@ -3211,5 +3109,5 @@ - Debug + Debug @@ -3227,6 +3125,7 @@ - This is a per-VM or global setting. Any combination of the above is - allowed. To restore the default behavior, use + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use the following + command: @@ -3243,6 +3142,6 @@ - where OPTION is one of the - following keywords: + where OPTION is one of the following + keywords: @@ -3251,5 +3150,5 @@ - All + All @@ -3263,5 +3162,5 @@ - About + About @@ -3276,44 +3175,45 @@ - Preferences - - - - - Do not show the Preferences - menu item in this menu. - - - - - - - NetworkAccessManager - - - - - Do not show the Network Operations Manager - menu item in this menu. - - - - - - - ResetWarnings - - - - - Do not show the Reset All Warnings - menu item in this menu. - - - - - - - Close + Preferences + + + + + Do not show the + Preferences menu item in + this menu. + + + + + + + NetworkAccessManager + + + + + Do not show the Network Operations + Manager menu item in this menu. + + + + + + + ResetWarnings + + + + + Do not show the Reset All + Warnings menu item in this menu. + + + + + + + Close @@ -3329,6 +3229,7 @@ - This is a per-VM or global setting. Any combination of the above is - allowed. To restore the default behavior, use + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use the following + command: @@ -3343,6 +3244,6 @@ - where OPTION is one of the - following keywords: + where OPTION is one of the following + keywords: @@ -3351,5 +3252,5 @@ - All + All @@ -3363,5 +3264,5 @@ - SettingsDialog + SettingsDialog @@ -3376,5 +3277,5 @@ - TakeSnapshot + TakeSnapshot @@ -3389,5 +3290,5 @@ - InformationDialog + InformationDialog @@ -3402,5 +3303,5 @@ - FileManagerDialog + FileManagerDialog @@ -3413,33 +3314,33 @@ - - - - Pause - - - - - Do not show the Pause menu item in this menu. - - - - - - - Reset - - - - - Do not show the Reset menu item in this menu. - - - - - - - - Shutdown + + + Pause + + + + + Do not show the Pause + menu item in this menu. + + + + + + + Reset + + + + + Do not show the Reset + menu item in this menu. + + + + + + + Shutdown @@ -3455,6 +3356,6 @@ - This is a per-VM or global setting. Any combination of the above is - allowed. To restore the default behavior, use + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use @@ -3469,6 +3370,6 @@ - where OPTION is one of the - following keywords: + where OPTION is one of the following + keywords: @@ -3477,5 +3378,5 @@ - All + All @@ -3489,17 +3390,18 @@ - Fullscreen - - - - - Do not show the Full-screen Mode menu item in this menu. - - - - - - - Seamless + Fullscreen + + + + + Do not show the Full-screen + Mode menu item in this menu. + + + + + + + Seamless @@ -3514,5 +3416,5 @@ - Scale + Scale @@ -3527,5 +3429,5 @@ - GuestAutoresize + GuestAutoresize @@ -3540,5 +3442,5 @@ - AdjustWindow + AdjustWindow @@ -3553,96 +3455,89 @@ - TakeScreenshot - - - - - Do not show the - Take Screenshot... menu item in - this menu. - - - - - - - Recording - - - - - Do not show the - Recording menu item in - this menu. - - - - - - - VRDEServer - - - - - Do not show the - Remote Display menu item in - this menu. - - - - - - - MenuBar - - - - - Do not show the - Menu Bar menu item in - this menu. - - - - - - - MenuBarSettings - - - - - Do not show the - Menu Bar Settings... menu item in - this menu. - - - - - - - StatusBar - - - - - Do not show the - Status Bar menu item in - this menu. - - - - - - - StatusbarSettings - - - - - Do not show the - Statusbar Settings... menu item in - this menu. + TakeScreenshot + + + + + Do not show the Take + Screenshot... menu item in this menu. + + + + + + + Recording + + + + + Do not show the Recording + menu item in this menu. + + + + + + + VRDEServer + + + + + Do not show the Remote + Display menu item in this menu. + + + + + + + MenuBar + + + + + Do not show the Menu Bar + menu item in this menu. + + + + + + + MenuBarSettings + + + + + Do not show the Menu Bar + Settings... menu item in this menu. + + + + + + + StatusBar + + + + + Do not show the Status + Bar menu item in this menu. + + + + + + + StatusbarSettings + + + + + Do not show the Statusbar + Settings... menu item in this menu. @@ -3652,11 +3547,11 @@ - This is a per-VM or global setting. Any combination of the above is - allowed. To restore the default behavior, use - - - VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions - - + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + + +VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions + + Use the following command to disable certain actions of the Input menu: @@ -3666,6 +3561,6 @@ - where OPTION is one of the - following keywords: + where OPTION is one of the following + keywords: @@ -3674,5 +3569,5 @@ - All + All @@ -3685,164 +3580,155 @@ - - Keyboard - - - - - Do not show the - Keyboard menu item in - this menu. - - - - - - - KeyboardSettings - - - - - Do not show the - Keyboard Settings... menu item in - this menu. - - - - - - - SoftKeyboard - - - - - Do not show the - Soft Keyboard... menu item in - this menu. - - - - - - - TypeCAD - - - - - Do not show the - Insert Ctrl-Alt-Del menu item in - this menu. - - - - - - - TypeCABS - - - - - Do not show the - Insert Ctrl-Alt-Backspace menu item in - this menu. - - - - - - - TypeCtrlBreak - - - - - Do not show the - Insert Ctrl-Break menu item in - this menu. - - - - - - - TypeInsert - - - - - Do not show the - Insert Insert menu item in - this menu. - - - - - - - TypePrintScreen - - - - - Do not show the - Insert Print Screen menu item in - this menu. - - - - - - - TypeAltPrintScreen - - - - - Do not show the - Insert Alt Print Screen menu item in - this menu. - - - - - - - TypeHostKeyCombo - - - - - Do not show the - Insert Host Key Combo menu item in - this menu. - - - - - - - MouseIntegration - - - - - Do not show the - MouseIntegration menu item in - this menu. - - + + Keyboard + + + + + Do not show the Keyboard + menu item in this menu. + + + + + + + KeyboardSettings + + + + + Do not show the Keyboard + Settings... menu item in this menu. + + + + + + + SoftKeyboard + + + + + Do not show the Soft + Keyboard... menu item in this menu. + + + + + + + TypeCAD + + + + + Do not show the Insert + Ctrl-Alt-Del menu item in this menu. + + + + + + + TypeCABS + + + + + Do not show the Insert + Ctrl-Alt-Backspace menu item in this menu. + + + + + + + TypeCtrlBreak + + + + + Do not show the Insert + Ctrl-Break menu item in this menu. + + + + + + + TypeInsert + + + + + Do not show the Insert + Insert menu item in this menu. + + + + + + + TypePrintScreen + + + + + Do not show the Insert Print + Screen menu item in this menu. + + + + + + + TypeAltPrintScreen + + + + + Do not show the Insert Alt Print + Screen menu item in this menu. + + + + + + + TypeHostKeyCombo + + + + + Do not show the Insert Host Key + Combo menu item in this menu. + + + + + + + MouseIntegration + + + + + Do not show the + MouseIntegration menu + item in this menu. + + - - This is a per-VM or global setting. Any combination of the above is - allowed. To restore the default behavior, use - - - VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions + + + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + + +VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions @@ -3854,6 +3740,6 @@ - where OPTION is one of the - following keywords to disable actions in the + where OPTION is one of the following keywords + to disable actions in the Devices menu: @@ -3863,5 +3749,5 @@ - All + All @@ -3875,17 +3761,18 @@ - HardDrives - - - - - Do not show the Hard Disks menu item in this menu. - - - - - - - OpticalDevices + HardDrives + + + + + Do not show the Hard + Disks menu item in this menu. + + + + + + + OpticalDevices @@ -3900,5 +3787,5 @@ - FloppyDevices + FloppyDevices @@ -3913,32 +3800,31 @@ - Audio - - - - - Do not show the Audio - menu item in this menu. - - - - - - - Network - - - - - Do not show the Network - menu item in this menu. - - - - - - - - NetworkSettings + Audio + + + + + Do not show the Audio + menu item in this menu. + + + + + + + Network + + + + + Do not show the Network + menu item in this menu. + + + + + + + NetworkSettings @@ -3953,44 +3839,44 @@ - USBDevices - - - - - Do not show the USB - menu item in this menu. - - - - - - - WebCams - - - - - Do not show the WebCams - menu item in this menu. - - - - - - - SharedFolders - - - - - Do not show the Shared Folders - menu item in this menu. - - - - - - - SharedFoldersSettings + USBDevices + + + + + Do not show the USB menu + item in this menu. + + + + + + + WebCams + + + + + Do not show the WebCams + menu item in this menu. + + + + + + + SharedFolders + + + + + Do not show the Shared + Folders menu item in this menu. + + + + + + + SharedFoldersSettings @@ -4005,5 +3891,5 @@ - SharedClipboard + SharedClipboard @@ -4018,5 +3904,5 @@ - DragAndDrop + DragAndDrop @@ -4031,5 +3917,5 @@ - InstallGuestTools + InstallGuestTools @@ -4045,6 +3931,6 @@ - This is a per-VM or global setting. Any combination of the above is - allowed. To restore the default behavior, use + This is a per-VM or global or global setting. Any combination of + the above is allowed. To restore the default behavior, use @@ -4059,8 +3945,7 @@ - where OPTION is one of the - following keywords to disable actions in the - Debug menu, which is normally completely - disabled: + where OPTION is one of the following keywords + to disable actions in the Debug menu, which + is normally completely disabled: @@ -4069,5 +3954,5 @@ - All + All @@ -4081,5 +3966,5 @@ - Statistics + Statistics @@ -4095,5 +3980,5 @@ - CommandLine + CommandLine @@ -4108,5 +3993,5 @@ - Logging + Logging @@ -4122,5 +4007,5 @@ - LogDialog + LogDialog @@ -4135,5 +4020,5 @@ - GuestControlConsole + GuestControlConsole @@ -4149,6 +4034,6 @@ - This is a per-VM or global setting. Any combination of the above is - allowed. To restore the default behavior, use + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use @@ -4163,8 +4048,7 @@ - where OPTION is one of the - following keywords to disable actions in the - Help menu, which is normally - completely disabled: + where OPTION is one of the following keywords + to disable actions in the Help + menu, which is normally completely disabled: @@ -4173,5 +4057,5 @@ - All + All @@ -4185,5 +4069,5 @@ - Contents + Contents @@ -4199,5 +4083,5 @@ - WebSite + WebSite @@ -4211,52 +4095,52 @@ - - BugTracker - - - - - Do not show the - VirtualBox Bug Tracker... menu item in - this menu. - - - - - - - Forums - - - - - Do not show the - VirtualBox Forums... menu item in this menu. - - - - - - - Oracle - - - - - Do not show the - Oracle Web Site... menu item in this menu. - - - - - - - About - - - - - Do not show the About VirtualBox... - menu item in this menu. Only for non-Mac OS X hosts. + + BugTracker + + + + + Do not show the VirtualBox Bug + Tracker... menu item in this menu. + + + + + + + Forums + + + + + Do not show the VirtualBox + Forums... menu item in this menu. + + + + + + + Oracle + + + + + Do not show the Oracle Web + Site... menu item in this menu. + + + + + + + About + + + + + Do not show the About + VirtualBox... menu item in this menu. Only for + non-Mac OS X hosts. @@ -4266,6 +4150,6 @@ - This is a per-VM or global setting. Any combination of the above is - allowed. To restore the default behavior, use + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use @@ -4285,6 +4169,6 @@ - where OPTION is one of the - following keywords: + where OPTION is one of the following + keywords: @@ -4293,5 +4177,5 @@ - HardDisks + HardDisks @@ -4307,5 +4191,5 @@ - OpticalDisks + OpticalDisks @@ -4321,5 +4205,5 @@ - FloppyDisks + FloppyDisks @@ -4335,5 +4219,5 @@ - Network + Network @@ -4350,5 +4234,5 @@ - USB + USB @@ -4362,5 +4246,5 @@ - SharedFolders + SharedFolders @@ -4374,5 +4258,5 @@ - Capture + Capture @@ -4386,5 +4270,5 @@ - Features + Features @@ -4398,5 +4282,5 @@ - Mouse + Mouse @@ -4410,5 +4294,5 @@ - Keyboard + Keyboard @@ -4423,7 +4307,7 @@ - This is a per-VM or global setting. Any combination of the above is - allowed. If all options are specified, no icons are displayed in - the status bar of the VM window. To restore the default + This is a per-VM or global setting. Any combination of the above + is allowed. If all options are specified, no icons are displayed + in the status bar of the VM window. To restore the default behavior, use @@ -4441,9 +4325,8 @@ -VBoxManage setextradata "VM name" GUI/RestrictedVisualStates OPTION[,OPTION...] - - - where OPTION is one of the - following keywords: +$ VBoxManage setextradata VM-name GUI/RestrictedVisualStates property[,property...] + + + property is one of the following: @@ -4452,5 +4335,5 @@ - Fullscreen + Fullscreen @@ -4464,5 +4347,5 @@ - Seamless + Seamless @@ -4476,5 +4359,5 @@ - Scale + Scale @@ -4489,9 +4372,10 @@ - This is a per-VM setting. Any combination of the above is - allowed. To restore the default behavior, use - - -VBoxManage setextradata "VM name" GUI/RestrictedVisualStates + This is a per-VM setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + + +$ VBoxManage setextradata VM-name GUI/RestrictedVisualStates @@ -4512,5 +4396,5 @@ -VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...." +$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...." @@ -4539,5 +4423,5 @@ - TakeSnapshot + TakeSnapshot @@ -4550,5 +4434,5 @@ - TakeScreenshot + TakeScreenshot @@ -4561,5 +4445,5 @@ - MouseIntegration + MouseIntegration @@ -4572,5 +4456,5 @@ - TypeCAD + TypeCAD @@ -4583,5 +4467,5 @@ - TypeCABS + TypeCABS @@ -4594,5 +4478,5 @@ - Pause + Pause @@ -4605,5 +4489,5 @@ - Reset + Reset @@ -4614,5 +4498,5 @@ - SaveState + SaveState @@ -4623,5 +4507,5 @@ - Shutdown + Shutdown @@ -4634,5 +4518,5 @@ - PowerOff + PowerOff @@ -4643,5 +4527,5 @@ - Close + Close @@ -4654,5 +4538,5 @@ - FullscreenMode + FullscreenMode @@ -4665,5 +4549,5 @@ - SeamlessMode + SeamlessMode @@ -4676,5 +4560,5 @@ - ScaleMode + ScaleMode @@ -4687,5 +4571,5 @@ - GuestAutoResize + GuestAutoResize @@ -4698,5 +4582,5 @@ - WindowAdjust + WindowAdjust @@ -4709,5 +4593,5 @@ - PopupMenu + PopupMenu @@ -4721,5 +4605,5 @@ - SettingsDialog + SettingsDialog @@ -4732,5 +4616,5 @@ - InformationDialog + InformationDialog @@ -4743,5 +4627,5 @@ - NetworkAdaptersDialog + NetworkAdaptersDialog @@ -4752,5 +4636,5 @@ - SharedFoldersDialog + SharedFoldersDialog @@ -4761,5 +4645,5 @@ - InstallGuestAdditions + InstallGuestAdditions @@ -4779,5 +4663,5 @@ -VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None" +$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None" @@ -4792,9 +4676,8 @@ -VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...] - - - where OPTION is one of the - following keywords: +$ VBoxManage setextradata VM-name GUI/RestrictedCloseActions property[,property...] + + + property is one of the following: @@ -4803,5 +4686,5 @@ - SaveState + SaveState @@ -4816,5 +4699,5 @@ - Shutdown + Shutdown @@ -4829,5 +4712,5 @@ - PowerOff + PowerOff @@ -4841,5 +4724,5 @@ - PowerOffRestoringSnapshot + PowerOffRestoringSnapshot @@ -4854,5 +4737,5 @@ - Detach + Detach @@ -4868,7 +4751,7 @@ - This is a per-VM setting. Any combination of the above is - allowed. If all options are specified, the VM cannot be shut - down at all. + This is a per-VM setting. You can specify any combination of + properties. If all properties are specified, the VM cannot be + shut down. @@ -4886,9 +4769,8 @@ -VBoxManage setextradata "VM name" GUI/DefaultCloseAction ACTION - - - where ACTION is one of the - following keywords: +$ VBoxManage setextradata VM-name GUI/DefaultCloseAction action + + + action is one of the following: @@ -4897,5 +4779,5 @@ - SaveState + SaveState @@ -4909,5 +4791,5 @@ - Shutdown + Shutdown @@ -4922,5 +4804,5 @@ - PowerOff + PowerOff @@ -4934,5 +4816,5 @@ - PowerOffRestoringSnapshot + PowerOffRestoringSnapshot @@ -4947,5 +4829,5 @@ - Detach + Detach @@ -4960,7 +4842,7 @@ - This is a per-VM setting. Any combination of the above is - allowed. If all options are specified, the VM cannot be shut - down at all. + This is a per-VM setting. You can specify any combination of + properties. If all properties are specified, the VM cannot be + shut down. @@ -4982,9 +4864,8 @@ -VBoxManage setextradata "VM name" GUI/GuruMeditationHandler MODE - - - where MODE is one of the - following keywords: +$ VBoxManage setextradata VM-name GUI/GuruMeditationHandler mode + + + mode is one of the following: @@ -4993,5 +4874,5 @@ - Default + Default @@ -5006,5 +4887,5 @@ - PowerOff + PowerOff @@ -5020,5 +4901,5 @@ - Ignore + Ignore @@ -5062,9 +4943,8 @@ -VBoxManage setextradata "VM name" GUI/MouseCapturePolicy MODE - - - where MODE is one of the - following keywords: +VBoxManage setextradata VM-name GUI/MouseCapturePolicy mode + + + mode is one of the following: @@ -5073,5 +4953,5 @@ - Default + Default @@ -5085,5 +4965,5 @@ - HostComboOnly + HostComboOnly @@ -5097,5 +4977,5 @@ - Disabled + Disabled @@ -5146,16 +5026,15 @@ - Removing Certain Modes of Networking from the GUI - - - It is possible to remove networking modes from - &product-name; GUI. To achieve this: - - -VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes OPTION[,OPTION...] - - - where OPTION is one of the - following keywords: + Removing Certain Modes of Networking From the GUI + + + It is possible to remove networking modes from &product-name; + GUI. To do this, use the following command: + + +VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes property[,property...] + + + property is one of the following: @@ -5164,5 +5043,5 @@ - NAT + NAT @@ -5177,63 +5056,63 @@ - NATNetwork - - - - - Remove the NAT network option - from the GUI. - - - - - - - BridgetAdapter - - - - - Remove the Bridged networking option - from the GUI. - - - - - - - InternalNetwork - - - - - Remove the Internal networking option - from the GUI. - - - - - - - HostOnlyAdapter - - - - - Remove the Host Only networking option - from the GUI. - - - - - - - GenericDriver - - - - - Remove the Generic networking option - from the GUI. + NATNetwork + + + + + Remove the NAT network + option from the GUI. + + + + + + + BridgedAdapter + + + + + Remove the Bridged + networking option from the GUI. + + + + + + + InternalNetwork + + + + + Remove the Internal + networking option from the GUI. + + + + + + + HostOnlyAdapter + + + + + Remove the Host Only + networking option from the GUI. + + + + + + + GenericDriver + + + + + Remove the Generic + networking option from the GUI. @@ -5242,14 +5121,14 @@ - - - This is a global setting. Any combination of the above is - allowed. To restore the default behavior, use + + This is a global setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes - + @@ -5259,13 +5138,12 @@ - The &product-name; web service, - vboxwebsrv, is used for - controlling &product-name; remotely. It is documented in detail in - the &product-name; Software Development Kit (SDK). See - . As the client base using this - interface is growing, we added start scripts for the various - operation systems we support. The following sections describe how - to use them. The &product-name; web service is never started - automatically as a result of a standard installation. + The &product-name; web service, vboxwebsrv, is + used for controlling &product-name; remotely. It is documented in + detail in the &product-name; Software Development Kit (SDK). See + . Web service start scripts are + available for supported host operating systems. The following + sections describe how to use the scripts. The &product-name; web + service is never started automatically as a result of a standard + installation. @@ -5277,12 +5155,11 @@ On Linux, the web service can be automatically started during host boot by adding appropriate parameters to the file - /etc/default/virtualbox. There - is one mandatory parameter, - VBOXWEB_USER, which must be set - to the user which will later start the VMs. The parameters in - the following table all start with the - VBOXWEB_ prefix string. For - example: VBOXWEB_HOST and - VBOXWEB_PORT. + /etc/default/virtualbox. There is one + mandatory parameter, VBOXWEB_USER, which must + be set to the user which will later start the VMs. The + parameters in the following table all start with the + VBOXWEB_ prefix string. For example: + VBOXWEB_HOST and + VBOXWEB_PORT. @@ -5306,5 +5183,5 @@ - USER + USER @@ -5315,5 +5192,5 @@ - HOST + HOST @@ -5326,5 +5203,5 @@ - PORT + PORT @@ -5337,5 +5214,5 @@ - SSL_KEYFILE + SSL_KEYFILE @@ -5346,5 +5223,5 @@ - SSL_PASSWORDFILE + SSL_PASSWORDFILE @@ -5355,5 +5232,5 @@ - SSL_CACERT + SSL_CACERT @@ -5364,5 +5241,5 @@ - SSL_CAPATH + SSL_CAPATH @@ -5373,5 +5250,5 @@ - SSL_DHFILE + SSL_DHFILE @@ -5382,5 +5259,5 @@ - SSL_RANDFILE + SSL_RANDFILE @@ -5391,5 +5268,5 @@ - TIMEOUT + TIMEOUT @@ -5402,5 +5279,5 @@ - CHECK_INTERVAL + CHECK_INTERVAL @@ -5413,5 +5290,5 @@ - THREADS + THREADS @@ -5424,5 +5301,5 @@ - KEEPALIVE + KEEPALIVE @@ -5436,5 +5313,5 @@ - ROTATE + ROTATE @@ -5447,5 +5324,5 @@ - LOGSIZE + LOGSIZE @@ -5458,5 +5335,5 @@ - LOGINTERVAL + LOGINTERVAL @@ -5473,8 +5350,8 @@ - Setting the parameter - SSL_KEYFILE enables the SSL/TLS - support. Using encryption is strongly encouraged, as otherwise - everything, including passwords, is transferred in clear text. + Setting the parameter SSL_KEYFILE enables the + SSL/TLS support. Using encryption is strongly encouraged, as + otherwise everything, including passwords, is transferred in + clear text. @@ -5497,12 +5374,12 @@ - showing the + The table in showing the parameter names and defaults also applies for Oracle Solaris. The parameter names must be changed to lowercase and a prefix of - config/ has to be added. For - example: config/user or - config/ssl_keyfile. If you make - any change, do not forget to run the following command to put - the changes into effect immediately: + config/ has to be added. For example: + config/user or + config/ssl_keyfile. If you make any change, + do not forget to run the following command to put the changes + into effect immediately: @@ -5538,10 +5415,8 @@ On Mac OS X, launchd is used to start the &product-name; webservice. An example configuration file can be found in - $HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist. - It can be enabled by changing the - Disabled key from - true to - false. To manually start the - service use the following command: + $HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist. + It can be enabled by changing the Disabled + key from true to false. To + manually start the service use the following command: @@ -5555,5 +5430,5 @@ https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html. + url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html" />. @@ -5568,7 +5443,7 @@ The memory ballooning service, formerly known as - VBoxBalloonCtrl, was renamed to - VBoxWatchdog. This service now incorporates the following host - services that are meant to be run in a server environment: + VBoxBalloonCtrl, was renamed to VBoxWatchdog. + This service now incorporates the following host services that are + meant to be run in a server environment: @@ -5767,5 +5642,5 @@ - none. This has no effect. + none. This has no effect. @@ -5773,6 +5648,5 @@ - pause. Pauses the execution - of a VM. + pause. Pauses the execution of a VM. @@ -5780,7 +5654,7 @@ - poweroff. Shuts down the VM - by pressing the virtual power button. The VM will not have - the chance of saving any data or veto the shutdown process. + poweroff. Shuts down the VM by pressing + the virtual power button. The VM will not have the chance of + saving any data or veto the shutdown process. @@ -5788,7 +5662,7 @@ - save. Saves the current - machine state and powers off the VM afterwards. If saving - the machine state fails the VM will be paused. + save. Saves the current machine state and + powers off the VM afterwards. If saving the machine state + fails the VM will be paused. @@ -5796,9 +5670,8 @@ - shutdown. Shuts down the VM - in a gentle way by sending an - ACPI shutdown event to the - VM's operating system. The OS then has the chance of doing a - clean shutdown. + shutdown. Shuts down the VM in a gentle + way by sending an ACPI shutdown event to + the VM's operating system. The OS then has the chance of + doing a clean shutdown. @@ -5815,5 +5688,5 @@ For more advanced options and parameters like verbose logging check the built-in command line help accessible with - --help. + . @@ -5827,21 +5700,18 @@ On Linux, the watchdog service can be automatically started during host boot by adding appropriate parameters to the file - /etc/default/virtualbox. There - is one mandatory parameter, - VBOXWATCHDOG_USER, which must - be set to the user which will later start the VMs. For backward - compatibility you can also specify - VBOXBALLOONCTRL_USER. + /etc/default/virtualbox. There is one + mandatory parameter, VBOXWATCHDOG_USER, which + must be set to the user which will later start the VMs. For + backward compatibility you can also specify + VBOXBALLOONCTRL_USER. The parameters in the following table all start with the - VBOXWATCHDOG_ prefix string. - For example: - VBOXWATCHDOG_BALLOON_INTERVAL - and VBOXWATCHDOG_LOGSIZE. - Legacy parameters such as - VBOXBALLOONCTRL_INTERVAL can - still be used. + VBOXWATCHDOG_ prefix string. For example: + VBOXWATCHDOG_BALLOON_INTERVAL and + VBOXWATCHDOG_LOGSIZE. Legacy parameters such + as VBOXBALLOONCTRL_INTERVAL can still be + used. @@ -5865,5 +5735,5 @@ - USER + USER @@ -5874,5 +5744,5 @@ - ROTATE + ROTATE @@ -5885,5 +5755,5 @@ - LOGSIZE + LOGSIZE @@ -5896,5 +5766,5 @@ - LOGINTERVAL + LOGINTERVAL @@ -5908,5 +5778,5 @@ - BALLOON_INTERVAL + BALLOON_INTERVAL @@ -5920,5 +5790,5 @@ - BALLOON_INCREMENT + BALLOON_INCREMENT @@ -5931,5 +5801,5 @@ - BALLOON_DECREMENT + BALLOON_DECREMENT @@ -5942,5 +5812,5 @@ - BALLOON_LOWERLIMIT + BALLOON_LOWERLIMIT @@ -5953,5 +5823,5 @@ - BALLOON_SAFETYMARGIN + BALLOON_SAFETYMARGIN @@ -5988,10 +5858,9 @@ also applies for Oracle Solaris. The parameter names must be changed to - lowercase and a prefix of - config/ has to be added. For - example: config/user or - config/balloon_safetymargin. If - you made any change, do not forget to run the following command - to put the changes into effect immediately: + lowercase and a prefix of config/ has to be + added. For example: config/user or + config/balloon_safetymargin. If you made any + change, do not forget to run the following command to put the + changes into effect immediately: @@ -6061,5 +5930,5 @@ -VBoxManage modifyvm "VM name" --vrdeproperty VNCPassword=secret +VBoxManage modifyvm VM-name --vrdeproperty VNCPassword=secret @@ -6095,26 +5964,23 @@ On Linux, the autostart service is activated by setting two - variables in - /etc/default/virtualbox. The - first one is VBOXAUTOSTART_DB - which contains an absolute path to the autostart database - directory. The directory should have write access for every user - who should be able to start virtual machines automatically. - Furthermore the directory should have the sticky bit set. The - second variable is - VBOXAUTOSTART_CONFIG which - points the service to the autostart configuration file which is - used during boot to determine whether to allow individual users - to start a VM automatically and configure startup delays. The - configuration file can be placed in - /etc/vbox and contains several - options. One is default_policy - which controls whether the autostart service allows or denies to - start a VM for users which are not in the exception list. The - exception list starts with - exception_list and contains a - comma separated list with usernames. Furthermore a separate - startup delay can be configured for every user to avoid - overloading the host. A sample configuration is given below: + variables in /etc/default/virtualbox. The + first one is VBOXAUTOSTART_DB which contains + an absolute path to the autostart database directory. The + directory should have write access for every user who should be + able to start virtual machines automatically. Furthermore the + directory should have the sticky bit set. The second variable is + VBOXAUTOSTART_CONFIG which points the service + to the autostart configuration file which is used during boot to + determine whether to allow individual users to start a VM + automatically and configure startup delays. The configuration + file can be placed in /etc/vbox and + contains several options. One is + default_policy which controls whether the + autostart service allows or denies to start a VM for users which + are not in the exception list. The exception list starts with + exception_list and contains a comma separated + list with usernames. Furthermore a separate startup delay can be + configured for every user to avoid overloading the host. A + sample configuration is given below: @@ -6135,13 +6001,13 @@ allow = false } - - - - Every user who wants to enable autostart for individual machines - has to set the path to the autostart database directory with the + + + + Any user who wants to enable autostart for individual machines + must set the path to the autostart database directory with the following command: -VBoxManage setproperty autostartdbpath <Autostart directory> +VBoxManage setproperty autostartdbpath autostart-directory @@ -6153,11 +6019,11 @@ On Oracle Solaris hosts, the &product-name; autostart daemon is - integrated into the SMF framework. To enable it you have to - point the service to an existing configuration file which has - the same format as on Linux, see - . For example: - - -svccfg -s svc:/application/virtualbox/autostart:default setprop \ + integrated into the SMF framework. To enable it you must point + the service to an existing configuration file which has the same + format as on Linux, see . For + example: + + +# svccfg -s svc:/application/virtualbox/autostart:default setprop \ config/config=/etc/vbox/autostart.cfg @@ -6167,9 +6033,9 @@ -svcadm enable svc:/application/virtualbox/autostart:default - - - For more information about SMF, please refer to the Oracle - Solaris documentation. +# svcadm enable svc:/application/virtualbox/autostart:default + + + For more information about SMF, see the Oracle Solaris + documentation. @@ -6183,12 +6049,11 @@ On Mac OS X, launchd is used to start the &product-name; autostart service. An example configuration file can be found in - /Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist. + /Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist. To enable the service copy the file to - /Library/LaunchDaemons and - change the Disabled key from - true to - false. Furthermore replace the - second parameter to an existing configuration file which has the - same format as on Linux, see . + /Library/LaunchDaemons and change the + Disabled key from true to + false. Furthermore replace the second + parameter to an existing configuration file which has the same + format as on Linux, see . @@ -6197,5 +6062,5 @@ -launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist +# launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist @@ -6206,5 +6071,5 @@ http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html. + url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html" />. @@ -6213,52 +6078,45 @@ - Windows: Starting the Autostart Service With windows service - - - On Windows, the autostarting is implemented as Windows service. - The service is installed for every user with her/his own credentials. - Before installing any autostart services on a system you have to define - the VBOXAUTOSTART_CONFIG environment - variable in the system variables with the path to the config file. - The config file has the same format as on Linux, - see , except the user name - can be specified using following formats: "user", "domain\user", - ".\user" and "user@domain". - - - - To activate the autostart ability for particular user a member of + Windows: Starting the Autostart Service With a Windows service + + + On Windows, autostarting is implemented as a Windows service. + The service is installed for every user with their own + credentials. Before installing any autostart services on a + system you first have to define the + VBOXAUTOSTART_CONFIG environment variable in + the system variables with the path to the autostart + configuration file. The configuration file has the same format + as on Linux, see , except the + user name can be specified using the following formats: "user", + "domain\user", ".\user" and "user@domain". + + + + To enable autostarting for a particular user, a member of the administrators group must run the following command: - VBoxAutostartSvc install --user=<user> [--password-file=<password_file>] - - - The password file should contain the password followed by a line break. - The rest of the file is ignored. The user will be asked for a password - if the password file is not specified. - - - - To remove the autostart ability for particular user a member of +VBoxAutostartSvc install --user=<user> [--password-file=<password_file>] + + + The password file should contain the password followed by a line + break. The rest of the file is ignored. The user will be asked + for a password if the password file is not specified. + + + + To disable autostarting for particular user, a member of the administrators group must run the following command: - VBoxAutostartSvc delete --user=<user> - - - The user can be specified for both commands using following formats: - "user", "domain\user", ".\user" and "user@domain" - - - - Note: - - - - If user has changed his password a member of administrators group - must either reinstall the service or change the service credentials - using windows service manager. The autostart service can not be - installed for users with empty passwords due to Windows security policies. +VBoxAutostartSvc delete --user=<user> + + + If a user has changed their password then a member of the + administrators group must either reinstall the service or change + the service credentials using Windows Service Manager. Due to + Windows security policies, the autostart service cannot be + installed for users with empty passwords. @@ -6285,12 +6143,11 @@ -VBoxManage setextradata "VM name" "VBoxInternal2/SilentReconfigureWhilePaused" 1 - - - Storage attachments can be reconfigured while the VM is paused - afterwards using: - - -VBoxManage storageattach ... +$ VBoxManage setextradata VM-name "VBoxInternal2/SilentReconfigureWhilePaused" 1 + + + You can reconfigure storage attachments later while the VM is + paused by using the VBoxManage storageattach + command. + @@ -6353,5 +6210,5 @@ -VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0 +$ VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0 @@ -6362,6 +6219,6 @@ -VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1 -VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0 +$ VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1 +$ VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0 @@ -6386,6 +6243,8 @@ -VBoxManage setextradata "VM name" VBoxInternal/CPUM/IsaExts/SSE4.1 0 -VBoxManage setextradata "VM name" VBoxInternal/CPUM/IsaExts/SSE4.2 0 +$ VBoxManage setextradata VM-name \ +VBoxInternal/CPUM/IsaExts/SSE4.1 0 +$ VBoxManage setextradata VM-name \ +VBoxInternal/CPUM/IsaExts/SSE4.2 0 @@ -6407,8 +6266,8 @@ -VBoxManage setextradata "VM name" GUI/HidLedsSync 0 - - - This is a per-VM setting, which is enabled by default. +$ VBoxManage setextradata VM-name GUI/HidLedsSync 0 + + + This is a per-VM setting that is enabled by default. @@ -6428,5 +6287,5 @@ -VBoxManage controlvm "VM name" usbattach "device uuid|address" --capturefile "filename" +VBoxManage controlvm VM-name usbattach device uuid|address --capturefile filename @@ -6435,13 +6294,13 @@ -VBoxManage setextradata "VM name" \ - VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename "filename" +VBoxManage setextradata VM-name \ +VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename filename The command above enables capturing on the root hub attached to the EHCI controller. To enable it for the OHCI or XHCI controller - replace usb-ehci with - usb-ohci or - usb-xhci respectively. + replace usb-ehci with + usb-ohci or usb-xhci, + respectively. @@ -6471,6 +6330,6 @@ -VBoxManage setextradata "VM name"\ - VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000 +VBoxManage setextradata VM-name \ +VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000 @@ -6482,6 +6341,6 @@ -VBoxManage setextradata "VM name" \ - VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000 +VBoxManage setextradata VM-name \ +VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000 @@ -6618,6 +6477,6 @@ -VBoxManage encryptmedium "uuid|filename" \ - --newpassword "file|-" --cipher "cipher id" --newpasswordid "id" +VBoxManage encryptmedium uuid|filename \ +--newpassword filename|- --cipher cipher-ID --newpasswordid "ID @@ -6630,10 +6489,9 @@ The cipher parameter specifies the cipher to use for encryption - and can be either - AES-XTS128-PLAIN64 or - AES-XTS256-PLAIN64. The - specified password identifier can be freely chosen by the user - and is used for correct identification when supplying multiple - passwords during VM startup. + and can be either AES-XTS128-PLAIN64 or + AES-XTS256-PLAIN64. The specified password + identifier can be freely chosen by the user and is used for + correct identification when supplying multiple passwords during + VM startup. @@ -6660,17 +6518,17 @@ -VBoxManage controlvm "uuid|vmname" addencpassword "id" "password" [--removeonsuspend "yes|no"] - - - The id parameter must be the - same as the password identifier supplied when encrypting the - images. password is the - password used when encrypting the images. The user can - optionally specify --removeonsuspend - "yes|no" to specify whether to remove the - password from VM memory when the VM is suspended. Before the VM - can be resumed, the user needs to supply the passwords again. - This is useful when a VM is suspended by a host suspend event - and the user does not want the password to remain in memory. +VBoxManage controlvm uuid|vmname addencpassword ID password [--removeonsuspend yes|no] + + + ID must be the same as the password + identifier supplied when encrypting the images. + password is the password used when + encrypting the images. Optionally, you can specify + to specify whether to + remove the password from VM memory when the VM is suspended. + Before the VM can be resumed, the user needs to supply the + passwords again. This is useful when a VM is suspended by a host + suspend event and the user does not want the password to remain + in memory. @@ -6688,5 +6546,5 @@ -VBoxManage encryptmedium "uuid|filename" --oldpassword "file|-" +VBoxManage encryptmedium uuid|filename --oldpassword file|- @@ -6705,6 +6563,6 @@ - In this section we cover debugging of guest operating systems - using interfaces supported by paravirtualization providers. + This section covers debugging of guest operating systems using + interfaces supported by paravirtualization providers. @@ -6738,21 +6596,19 @@ Key: - enabled + enabled - Value: 0 or - 1 + Value: 0 or 1 - Default: 0 + Default: 0 - Specify 1 to enable the - Hyper-V debug interface. If this key-value pair is not - specified or the value is not - 1, the Hyper-V debug + Specify 1 to enable the Hyper-V debug + interface. If this key-value pair is not specified or the + value is not 1, the Hyper-V debug interface is disabled regardless of other key-value pairs being present. @@ -6763,5 +6619,5 @@ Key: - address + address @@ -6783,5 +6639,5 @@ Key: - port + port @@ -6803,5 +6659,5 @@ Key: - vendor + vendor @@ -6812,7 +6668,6 @@ - Default: When debugging is enabled: - Microsoft Hv, otherwise: - VBoxVBoxVBox + Default: When debugging is enabled: Microsoft + Hv, otherwise: VBoxVBoxVBox @@ -6827,15 +6682,14 @@ Key: - hypercallinterface + hypercallinterface - Value: 0 or - 1 + Value: 0 or 1 - Default: 0 + Default: 0 @@ -6849,18 +6703,15 @@ - Key: - vsinterface + Key: vsinterface - Value: 0 or - 1 + Value: 0 or 1 - Default: When debugging is enabled, - 1, otherwise - 0 + Default: When debugging is enabled, 1, + otherwise 0 @@ -6913,5 +6764,5 @@ -VBoxManage showvminfo "VM name" +$ VBoxManage showvminfo VM-name @@ -6929,17 +6780,16 @@ debug support, Windows 7 and Vista do not. To use Hyper-V debugging with a Windows 7 or Vista guest, copy the file - kdvm.dll from a Windows - 8.0 installation. This file is typically located in - C:\Windows\System32. Copy - it to the same location in your Windows 7/Vista guest. - Make sure you copy the 32-bit or 64-bit version of the DLL - which matches your guest OS. + kdvm.dll from a Windows 8.0 + installation. This file is typically located in + C:\Windows\System32. Copy it to the + same location in your Windows 7/Vista guest. Make sure you + copy the 32-bit or 64-bit version of the DLL which matches + your guest OS. - Only Windows 8.0 ships - kdvm.dll. Windows 8.1 - and newer Windows versions do not. + Only Windows 8.0 ships kdvm.dll. + Windows 8.1 and newer Windows versions do not. @@ -6966,5 +6816,5 @@ -VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1" +$ VBoxManage modifyvm VM-name --paravirtdebug "enabled=1" @@ -6975,5 +6825,6 @@ -VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1,address=192.168.32.1,port=55000" +$ VBoxManage modifyvm VM-name \ +--paravirtdebug "enabled=1,address=192.168.32.1,port=55000" @@ -7071,15 +6922,13 @@ the NET tab, specify the UDP port number you used in the - paravirtdebug options. If - you did not specify any, leave it as 50000. Ensure that - the UDP port is not blocked by a firewall or other - security software. + paravirtdebug options. If you did not + specify any, leave it as 50000. Ensure that the UDP port + is not blocked by a firewall or other security software. In the Key field, enter - 1.2.3.4 or the encryption - key from the bcdedit - command in your Windows guest. + 1.2.3.4 or the encryption key from the + bcdedit command in your Windows guest. @@ -7167,5 +7016,5 @@ - /dev/input/by-path/platform-pcspkr-event-spkr + /dev/input/by-path/platform-pcspkr-event-spkr @@ -7177,5 +7026,5 @@ 2 - /dev/tty + /dev/tty Uses the terminal association of the VM process. VM @@ -7188,11 +7037,10 @@ - /dev/tty0 or - /dev/vc/0 + /dev/tty0 or + /dev/vc/0 - Can only be used by user - root or users with - cap_sys_tty_config + Can only be used by user root or + users with cap_sys_tty_config capability. @@ -7214,5 +7062,5 @@ - /dev/tty + /dev/tty @@ -7251,20 +7099,18 @@ -VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" N - - - Replace N with the code - representing the case you want to use. Changing this setting will - take effect when the VM is started next. It is safe to enable PC - speaker passthrough on all host OSes. It will only have an effect - on Linux. - - - - The VM log file, VBox.log, will - contain lines with the prefix PIT: - speaker: showing the PC speaker passthrough setup - activities. It gives hints which device it picked or why it - failed. +VBoxManage setextradata VM-name "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" N + + + Replace N with the code representing + the case you want to use. Changing this setting takes effect when + you next start the VM. It is safe to enable PC speaker passthrough + on all host OSes. It will only have an effect on Linux. + + + + The VM log file, VBox.log, contains lines + with the prefix PIT: speaker: showing the PC + speaker passthrough setup activities. It gives hints which device + it picked or why it failed. @@ -7273,14 +7119,13 @@ part. The real difficulty is making sure that &product-name; can access the necessary device, because in a typical Linux install - most of them can only be accessed by user - root. You should follow the - preferred way to persistently change this, such as by referring to - your distribution's documentation. Since there are countless Linux - distribution variants, we can only give the general hints that - there is often a way to give the X11 session user access to - additional devices, or you need to find a working solution using a - udev configuration file. If everything fails you might try setting - the permissions using a script which is run late enough in the - host system startup. + most of them can only be accessed by user root. + You should follow the preferred way to persistently change this, + such as by referring to your distribution's documentation. Since + there are countless Linux distribution variants, we can only give + the general hints that there is often a way to give the X11 + session user access to additional devices, or you need to find a + working solution using a udev configuration file. If everything + fails you might try setting the permissions using a script which + is run late enough in the host system startup. @@ -7322,10 +7167,10 @@ - To enable support for passing through USB/IP devices, the device - server exporting the devices must be added with the following - command: - - -VBoxManage usbdevsource add "Unique name" --backend "USBIP" --address "Device server[:port]" + To enable support for passing through USB/IP devices, use the + following command to add the device server that exports the + devices: + + +VBoxManage usbdevsource add unique-name --backend USB-IP --address device-server[:port] @@ -7340,5 +7185,5 @@ -VBoxManage usbdevsource remove "Unique name" +$ VBoxManage usbdevsource remove unique-name @@ -7349,15 +7194,13 @@ This section gives a brief overview on how to set up a Linux based system to act as a USB device server. The system on the - server requires that the - usbip-core.ko and - usbip-host.ko kernel drivers - are available, and that the USB/IP tools package is installed. - The particular installation method for the necessary tools - depends on which distribution is used. For example, for Debian - based systems, the following command should be used to install - the required tools: - - -apt-get install usbip-utils + server requires that the usbip-core.ko and + usbip-host.ko kernel drivers are available, + and that the USB/IP tools package is installed. The particular + installation method for the necessary tools depends on which + distribution is used. For example, for Debian based systems, use + the following command to install the required tools: + + +$ apt-get install usbip-utils @@ -7385,12 +7228,11 @@ If everything is installed, the USB/IP server needs to be - started as root using the - following command: - - -usbipd -D - - - Refer to the documentation for the installed distribution to + started as root using the following command: + + +# usbipd -D + + + See the documentation for the installed distribution to determine how to start the service when the system boots. @@ -7402,5 +7244,5 @@ -usbip bind -b "bus identifier" +# usbip bind -b "bus identifier" @@ -7408,5 +7250,5 @@ -usbip bind -b 4-2 +# usbip bind -b 4-2 @@ -7449,6 +7291,6 @@ - When using this feature, you might experience significant - &product-name; performance degradation on some host systems. + When using this feature, some host systems might experience + significant &product-name; performance degradation. @@ -7461,10 +7303,10 @@ - &product-name; supports nested virtualization. - This feature enables the passthrough of hardware virtualization - functions to the guest VM. That means that you can install a - hypervisor, such as &product-name;, Oracle VM Server or KVM, on - a &product-name; guest. You can then create and run VMs within the - guest VM. + &product-name; supports nested + virtualization. This feature enables the passthrough of + hardware virtualization functions to the guest VM. That means that + you can install a hypervisor, such as &product-name;, Oracle VM + Server or KVM, on an &product-name; guest. You can then create and + run VMs within the guest VM. Index: /trunk/doc/manual/en_US/user_BasicConcepts.xml =================================================================== --- /trunk/doc/manual/en_US/user_BasicConcepts.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_BasicConcepts.xml (revision 82350) @@ -458,45 +458,4 @@ 64-bit Guests - - - &product-name; enables you to run 64-bit guest OSes even on a - 32-bit host OS. To run a 64-bit guest OS on a 32-bit host - system, ensure that you meet the following conditions: - - - - - - - You need a 64-bit processor that has hardware virtualization - support. See . - - - - - - You must enable hardware virtualization for the particular - VM that requires 64-bit support. Software virtualization is - not supported for 64-bit VMs. - - - - - - To use 64-bit guest support on a 32-bit host OS, you must - select a 64-bit OS for the particular VM. Since supporting - 64 bits on 32-bit hosts incurs additional overhead, - &product-name; only enables this support only upon explicit - request. - - - - 64-bit hosts typically come with hardware virtualization - support. So, you can install a 64-bit guest OS in the guest - regardless of the settings. - - - - @@ -515,7 +474,7 @@ If you use the Create VM wizard - of the &product-name; graphical user interface (GUI), - &product-name; automatically uses the correct settings for each - selected 64-bit OS type. See . + of the VirtualBox Manager, &product-name; automatically uses the + correct settings for each selected 64-bit OS type. See + . @@ -868,8 +827,7 @@ - Input devices. By default, - &product-name; emulates a standard PS/2 keyboard and mouse. - These devices are supported by almost all past and present - OSes. + Input devices. &product-name; + can emulate a standard PS/2 keyboard and mouse. These devices + are supported by most guest OSes. @@ -877,17 +835,20 @@ In addition, &product-name; can provide virtual USB input devices to avoid having to capture mouse and keyboard, as - described in . - - - - - - Graphics. The &product-name; - graphics device, sometimes referred to as a VGA device, is not - based on any physical counterpart. This is unlike nearly all - other emulated devices. It is a simple, synthetic device which - provides compatibility with standard VGA and several extended - registers used by the VESA BIOS Extensions (VBE). + described in . + + + + + + Graphics. The default + &product-name; graphics device for Windows guests is an SVGA + device. For Linux guests, the default graphics device emulates + a VMware SVGA graphics device. See + . + + + + For legacy guest OSes, a VGA-compatible graphics device is + available. @@ -896,14 +857,12 @@ Storage. &product-name; - currently emulates the standard ATA interface found on Intel - PIIX3/PIIX4 chips, the SATA (AHCI) interface, and two SCSI - adapters (LSI Logic and BusLogic). See - for details. Whereas - providing one of these would be enough for &product-name; by - itself, this multitude of storage adapters is required for - compatibility with other hypervisors. Windows is particularly - picky about its boot devices, and migrating VMs between - hypervisors is very difficult or impossible if the storage - controllers are different. + emulates the most common types of hard disk controllers. See + . Whereas supporting + only one of these controllers would be enough for + &product-name; by itself, this multitude of storage adapters + is required for compatibility with other hypervisors. Windows + is very selective about its boot devices, and migrating VMs + between hypervisors is very difficult or impossible if the + storage controllers are different. @@ -912,6 +871,5 @@ Networking. See - . + . @@ -920,12 +878,13 @@ USB. &product-name; emulates - three USB host controllers: xHCI, EHCI, and OHCI. While xHCI - handles all USB transfer speeds, only guest OSes released - approximately after 2011 support xHCI. Note that for Windows 7 - guests, 3rd party drivers must be installed for xHCI support. - - - - Older OSes typically support OHCI and EHCI. The two + these types of USB host controllers: xHCI, EHCI, and OHCI. + While xHCI handles all USB transfer speeds, some legacy guest + OSes may not support xHCI. Note that for some legacy Windows + guests, third party drivers must be installed for xHCI + support. + + + + Legacy guest OSes typically support OHCI and EHCI. These two controllers are needed because OHCI only handles USB low-speed and full-speed devices (both USB 1.x and 2.0), while EHCI only @@ -935,7 +894,7 @@ The emulated USB controllers do not communicate directly with - devices on the host but rather with a virtual USB layer which - abstracts the USB protocol and enables the use of remote USB - devices. + devices on the host. Instead they communicate with a virtual + USB layer which abstracts the USB protocol and enables the use + of remote USB devices. @@ -977,10 +936,11 @@ - Name: The name under which - the VM is shown in the list of VMs in the main window. Under - this name, &product-name; also saves the VM's configuration - files. By changing the name, &product-name; renames these - files as well. As a result, you can only use characters - which are allowed in your host OS's file names. + Name: The name of the the + VM, as shown in the list of VMs in the main VirtualBox + Manager window. Using this name, &product-name; also saves + the VM's configuration files. If you change the name, + &product-name; renames these files as well. As a result, you + can only use characters which are allowed for file names on + your host OS. @@ -988,5 +948,5 @@ Note that internally, &product-name; uses unique identifiers (UUIDs) to identify virtual machines. You can display these - with VBoxManage. + using the VBoxManage commands. @@ -1077,6 +1037,6 @@ enables support for drag and drop. Select an object, such as a file, from the host or guest and directly copy or open it - on the guest or host. Multiple per-VM drag and drop modes - allow restricting access in either direction. + on the guest or host. Multiple drag and drop modes for a VM + enable restricting of access in either direction. @@ -1148,6 +1108,6 @@ - All files related to the virtual machine except disk images are - stored unencrypted. + All files related to the virtual machine except disk images + are stored unencrypted. @@ -1234,17 +1194,16 @@ Chipset: You can select - which chipset will be presented to the virtual machine. In - legacy versions of &product-name;, PIIX3 was the only - available option. For modern guest OSes such as Mac OS X, - that old chipset is no longer well supported. As a result, - &product-name; supports an emulation of the more modern ICH9 - chipset, which supports PCI express, three PCI buses, - PCI-to-PCI bridges and Message Signaled Interrupts (MSI). - This enables modern OSes to address more PCI devices and no - longer requires IRQ sharing. Using the ICH9 chipset it is - also possible to configure up to 36 network cards, up to 8 - network adapters with PIIX3. Note that the ICH9 support is - experimental and not recommended for guest OSes which do not - require it. + which chipset will be presented to the virtual machine. + PIIX3 is the default chipset for most guests. For some guest + OSes such as Mac OS X, the PIIX3 chipset is not well + supported. As a result, &product-name; supports an emulation + of the ICH9 chipset, which supports PCI express, three PCI + buses, PCI-to-PCI bridges and Message Signaled Interrupts + (MSI). This enables modern OSes to address more PCI devices + and no longer requires IRQ sharing. Using the ICH9 chipset + it is also possible to configure up to 36 network cards, + compared to a maximum of eight network adapters with PIIX3. + Note that ICH9 support is experimental and not recommended + for guest OSes which do not require it. @@ -1253,11 +1212,12 @@ Pointing Device: The - default virtual pointing devices for older guests is the - traditional PS/2 mouse. If set to USB - tablet, &product-name; reports to the virtual + default virtual pointing device for some guest OSes is the + traditional PS/2 mouse. If set to USB + Tablet, &product-name; reports to the virtual machine that a USB tablet device is present and communicates - mouse events to the virtual machine through this device. The - third setting is a USB Multi-Touch - Tablet which is suited for recent Windows guests. + mouse events to the virtual machine through this device. + Another setting is USB Multi-Touch + Tablet, which is suitable for guests running + Windows 8 or later. @@ -1277,15 +1237,15 @@ Enable I/O APIC: Advanced - Programmable Interrupt Controllers (APICs) are a newer x86 - hardware feature that have replaced old-style Programmable - Interrupt Controllers (PICs) in recent years. With an I/O - APIC, OSes can use more than 16 interrupt requests (IRQs) - and therefore avoid IRQ sharing for improved reliability. + Programmable Interrupt Controllers (APICs) are an x86 + hardware feature that have replaced Programmable Interrupt + Controllers (PICs). With an I/O APIC, OSes can use more than + 16 interrupt requests (IRQs) and therefore avoid IRQ sharing + for improved reliability. - Enabling the I/O APIC is required for - 64-bit guest OSes, especially Windows Vista. It is also + Enabling the I/O APIC is required, + especially for 64-bit Windows guest OSes. It is also required if you want to use more than one virtual CPU in a virtual machine. @@ -1302,8 +1262,7 @@ - All Windows OSes starting with Windows 2000 install - different kernels, depending on whether an I/O APIC is - available. As with ACPI, the I/O APIC therefore - must not be turned off after + All Windows OSes install different kernels, depending on + whether an I/O APIC is available. As with ACPI, the I/O + APIC therefore must not be turned off after installation of a Windows guest OS. Turning it on after installation will have no effect however. @@ -1343,17 +1302,17 @@ ACPI is the current industry standard to allow OSes to recognize hardware, configure motherboards and other devices and manage - power. As all modern PCs contain this feature and Windows and - Linux have been supporting it for years, it is also enabled by - default in &product-name;. ACPI can only be turned off using the - command line. See . + power. As most computers contain this feature and Windows and + Linux support ACPI, it is also enabled by default in + &product-name;. ACPI can only be turned off using the command + line. See . - All Windows OSes starting with Windows 2000 install different - kernels, depending on whether ACPI is available. This means - that ACPI must not be turned off after - installation of a Windows guest OS. However, turning it on - after installation will have no effect. + All Windows OSes install different kernels, depending on + whether ACPI is available. This means that ACPI must + not be turned off after installation of a Windows + guest OS. However, turning it on after installation will have + no effect. @@ -1460,5 +1419,5 @@ accuracy and performance of guest OSes. The options available are documented under the - paravirtprovider option in + option in . For further details on the paravirtualization providers, see @@ -1470,18 +1429,9 @@ Hardware Virtualization: - You can select for each virtual machine individually whether - &product-name; should use software or hardware - virtualization. + You can configure hardware virtualization features for each + virtual machine. - - - - Enable VT-x/AMD-V: - Enables Intel VT-x and AMD-V hardware extensions if the - host CPU supports them. - - @@ -1502,6 +1452,5 @@ Advanced users may be interested in technical details about - software versus hardware virtualization. See - . + hardware virtualization. See . @@ -1614,23 +1563,4 @@ - Enable 3D Acceleration: If - a virtual machine has Guest Additions installed, you can - select here whether the guest should support accelerated 3D - graphics. See . - - - - - - Enable 2D Video - Acceleration: If a virtual machine with Microsoft - Windows has Guest Additions installed, you can select here - whether the guest should support accelerated 2D video - graphics. See . - - - - - Graphics Controller: Specifies the graphics adapter type used by the guest VM. @@ -1661,4 +1591,9 @@ default graphics controller for Windows versions before Windows 7 and for Oracle Solaris. + + + + 3D acceleration is not supported for this graphics + controller. @@ -1681,4 +1616,23 @@ + + + + + Enable 3D Acceleration: If + a virtual machine has Guest Additions installed, you can + select here whether the guest should support accelerated 3D + graphics. See . + + + + + + Enable 2D Video + Acceleration: If a virtual machine with Microsoft + Windows has Guest Additions installed, you can select here + whether the guest should support accelerated 2D video + graphics. See . + @@ -1779,8 +1733,8 @@ - Quality: Use the slider to - set the the bit rate of the video in kilobits per second. - Increasing this value improves the appearance of the video - at the cost of an increased file size. + Video Quality: Use the + slider to set the the bit rate of the video in kilobits per + second. Increasing this value improves the appearance of the + video at the cost of an increased file size. @@ -1825,10 +1779,10 @@ - In a real PC, so-called storage controllers - connect physical disk drives to the rest of the computer. - Similarly, &product-name; presents virtual storage controllers to - a virtual machine. Under each controller, the virtual devices, - such as hard disks, CD/DVD or floppy drives, attached to the - controller are shown. + In a real computer, so-called storage + controllers connect physical disk drives to the rest of + the computer. Similarly, &product-name; presents virtual storage + controllers to a virtual machine. Under each controller, the + virtual devices, such as hard disks, CD/DVD or floppy drives, + attached to the controller are shown. @@ -1849,5 +1803,5 @@
Storage Settings for a Virtual Machine - + -
+ @@ -1921,9 +1875,9 @@ To add another virtual hard disk, or a CD/DVD or floppy drive, select the storage - controller to which it should be added (IDE, SATA, SCSI, SAS, - floppy controller) and then click the + controller to which it should be added (such as IDE, SATA, + SCSI, SAS, floppy controller) and then click the Add Disk button below the - tree. You can then either select Add - CD/DVD Device or Add Hard + tree. You can then either select Optical + Drive or Hard Disk. If you clicked on a floppy controller, you can add a floppy drive instead. Alternatively, right-click on @@ -1932,9 +1886,32 @@ - On the right part of the window, you can then set the - following: - - - + A dialog is displayed, enabling you to select an existing disk + image file or to create a new disk image file. Depending on + the type of disk image, the dialog is called + Hard Disk Selector, + Optical Disk Selector, or + Floppy Disk Selector. + + + + See for information on the image + file types that are supported by &product-name;. + + + + For virtual CD/DVD drives, the image files will typically be + in the standard ISO format instead. Most commonly, you will + select this option when installing an OS from an ISO file that + you have obtained from the Internet. For example, most Linux + distributions are available in this way. + + + + Depending on the type of disk image, you can set the following + Attributes for the disk image + in the right part of the Storage settings page: + + + @@ -1952,87 +1929,27 @@ - The image file to use. - - - - - - - For virtual hard disks, a button with a drop-down list - appears on the right, offering you to either select a - virtual hard disk - file using a standard file dialog or to - create a new hard - disk (image file). The latter option - displays the Create New - Disk wizard, described in - . - - - - For virtual floppy drives, a dialog enables you to - create and format a new floppy disk image - automatically. - - - - For details on the image file types that are - supported, see . - - - - - - For virtual CD/DVD drives, the image files will - typically be in the standard ISO format instead. Most - commonly, you will select this option when installing - an OS from an ISO file that you have obtained from the - Internet. For example, most Linux distributions are - available in this way. - - - - For virtual CD/DVD drives, the following additional - options are available: - - - - - - - If you select Host - Drive from the list, then the physical - device of the host computer is connected to the - VM, so that the guest OS can read from and write - to your physical device. This is, for instance, - useful if you want to install Windows from a real - installation CD. In this case, select your host - drive from the drop-down list presented. - - - - If you want to write, or burn, CDs or DVDs using - the host drive, you need to also enable the - Passthrough - option. See . - - - - - - If you select Remove Disk - from Virtual Drive, &product-name; will - present an empty CD/DVD drive to the guest into - which no media has been inserted. - - - - - - - - - - + Solid-state Drive + presents a virtual disk to the guest as a solid-state + device. + + + + + + Hot-pluggable presents a + virtual disk to the guest as a hot-pluggable device. + + + + + + For virtual CD/DVD drives, you can select + Live CD/DVD. This means + that the virtual optical disk is not removed from when the + guest system ejects it. + + + + @@ -2199,7 +2116,7 @@ VBoxManage command to set up virtual serial ports. For the latter, see - for information on the --uart, - --uartmode and - --uarttype options. + for information on the , + and + options. @@ -2250,10 +2167,4 @@ I/O base address and interrupt (IRQ). - - - See also - http://en.wikipedia.org/wiki/COM_(hardware_interface). - @@ -2280,10 +2191,9 @@ virtual serial port to a physical serial port on your host. On a Windows host, this will be a name like - COM1. On Linux or Oracle - Solaris hosts, it will be a device node like - /dev/ttyS0. - &product-name; will then simply redirect all data received - from and sent to the virtual serial port to the physical - device. + COM1. On Linux or Oracle Solaris hosts, + it will be a device node like + /dev/ttyS0. &product-name; will then + simply redirect all data received from and sent to the + virtual serial port to the physical device. @@ -2304,8 +2214,7 @@ through a named pipe. The pipe name must be in the format - \\.\pipe\<name> - where <name> - should identify the virtual machine but may be freely - chosen. + \\.\pipe\name + where name should identify + the virtual machine but may be freely chosen. @@ -2313,10 +2222,10 @@ - On a Mac, Linux, or Oracle Solaris host, a local + On a Mac OS, Linux, or Oracle Solaris host, a local domain socket is used instead. The socket filename must be chosen such that the user running &product-name; has sufficient privileges to create and - write to it. The /tmp - directory is often a good candidate. + write to it. The /tmp directory + is often a good candidate. @@ -2324,7 +2233,6 @@ On Linux there are various tools which can connect to a local domain socket or create one in server mode. - The most flexible tool is - socat and is - available as part of many distributions. + The most flexible tool is socat and + is available as part of many distributions. @@ -2396,8 +2304,8 @@ a virtual null-modem cable over the Internet or LAN, the other side can connect using TCP by specifying - hostname:port in the - Path/Address field. - The TCP socket will act in client mode if you select - the Connect to Existing + hostname:port + in the Path/Address + field. The TCP socket will act in client mode if you + select the Connect to Existing Pipe/Socket check box. @@ -2567,7 +2475,6 @@ in hexadecimal, and a colon separates the vendor from the product ID. For example, - 046d:c016 stands for - Logitech as a vendor, and the M-UV69a Optical Wheel - Mouse product. + 046d:c016 stands for Logitech as a + vendor, and the M-UV69a Optical Wheel Mouse product. @@ -2651,34 +2558,16 @@ &product-name; to capture devices when they are plugged in, and a USB device driver to claim USB devices for a particular - virtual machine. As opposed to &product-name; versions before - 1.4.0, system reboots are no longer necessary after installing - the driver. Also, you no longer need to replug devices for - &product-name; to claim them. - - - - On newer Linux hosts, &product-name; accesses USB devices + virtual machine. System reboots are not necessary after + installing the driver. Also, you do not need to replug devices + for &product-name; to claim them. + + + + On supported Linux hosts, &product-name; accesses USB devices through special files in the file system. When &product-name; is installed, these are made available to all users in the - vboxusers system group. In - order to be able to access USB from guest systems, make sure - that you are a member of this group. - - - - On older Linux hosts, USB devices are accessed using the - usbfs file system. Therefore, - the user executing &product-name; needs read and write - permission to the USB file system. Most distributions provide a - group, such as usbusers, which - the &product-name; user needs to be added to. Also, - &product-name; can only proxy to virtual machines USB devices - which are not claimed by a Linux host USB driver. The - Driver= entry in - /proc/bus/usb/devices will show - you which devices are currently claimed. See also - for details about - usbfs. + vboxusers system group. In order to be able + to access USB from guest systems, make sure that you are a + member of this group. @@ -2760,8 +2649,7 @@ &product-name; includes experimental support for the Extensible - Firmware Interface (EFI), which is a new industry standard - intended to eventually replace the legacy BIOS as the primary - interface for bootstrapping computers and certain system services - later. + Firmware Interface (EFI), which is an industry standard intended + to replace the legacy BIOS as the primary interface for + bootstrapping computers and certain system services later. @@ -3225,10 +3113,12 @@ It is currently not possible to manipulate EFI variables from - within a running guest. For example, setting the "boot-args" - variable by running the nvram - tool in a Mac OS X guest will not work. As an alternative way, - "VBoxInternal2/EfiBootArgs" extradata can be passed to a VM in - order to set the "boot-args" variable. To change the "boot-args" - EFI variable, use the following command: + within a running guest. For example, setting the + boot-args variable by running the + nvram tool in a Mac OS X guest will not work. + As an alternative method, + VBoxInternal2/EfiBootArgs extradata can be + passed to a VM in order to set the boot-args + variable. To change the boot-args EFI + variable, use the following command: Index: /trunk/doc/manual/en_US/user_ChangeLog.xml =================================================================== --- /trunk/doc/manual/en_US/user_ChangeLog.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_ChangeLog.xml (revision 82350) @@ -41,5 +41,5 @@ - https://www.virtualbox.org/wiki/Changelog. + . Index: /trunk/doc/manual/en_US/user_Frontends.xml =================================================================== --- /trunk/doc/manual/en_US/user_Frontends.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Frontends.xml (revision 82350) @@ -34,8 +34,5 @@ Oracle provides support for the VirtualBox Remote Display Protocol - (VRDP) in such an &product-name; extension package. When this - package is installed, &product-name; versions 4.0 and later - support VRDP the same way as binary, non-open source, versions of - &product-name; before 4.0 did. + (VRDP) in such an &product-name; extension package. @@ -55,15 +52,14 @@ -VBoxManage modifyvm "VM name" --vrde on - - - By default, the VRDP server uses TCP port - 3389. You will need to change the - default port if you run more than one VRDP server, since the port - can only be used by one server at a time. You might also need to - change it on Windows hosts since the default port might already be - used by the RDP server that is built into Windows itself. Ports - 5000 through 5050 are typically not used and might be a good - choice. +$ VBoxManage modifyvm VM-name --vrde on + + + By default, the VRDP server uses TCP port 3389. + You will need to change the default port if you run more than one + VRDP server, since the port can only be used by one server at a + time. You might also need to change it on Windows hosts since the + default port might already be used by the RDP server that is built + into Windows itself. Ports 5000 through 5050 are typically not + used and might be a good choice. @@ -76,8 +72,9 @@ dash between two port numbers to specify a range. The VRDP server will bind to one of the available ports from - the specified list. For example, VBoxManage - modifyvm "VM name" --vrdeport 5000,5010-5012 will - configure the server to bind to one of the ports 5000, 5010, 5011, - or 5012. See . + the specified list. For example, VBoxManage modifyvm + VM-name --vrdeport + 5000,5010-5012 configures the server to bind to one of + the ports 5000, 5010, 5011, or 5012. See + . @@ -92,7 +89,7 @@ - Support for IPv6 has been implemented in &product-name; 4.3. If - the host OS supports IPv6 the VRDP server will automatically - listen for IPv6 connections in addition to IPv4. + &product-name; supports IPv6. If the host OS supports IPv6 the + VRDP server will automatically listen for IPv6 connections in + addition to IPv4. @@ -134,7 +131,7 @@ - Replace 1.2.3.4 with the - host IP address, and 3389 - with a different port, if necessary. + Replace 1.2.3.4 with the host IP address, + and 3389 with a different port, if + necessary. @@ -145,6 +142,6 @@ IPv6 addresses must be enclosed in square brackets to - specify a port. For example: mstsc - [fe80::1:2:3:4]:3389 + specify a port. For example: mstsc + [fe80::1:2:3:4]:3389 @@ -153,11 +150,8 @@ When connecting to localhost in order to test the - connection, the addresses - localhost and - 127.0.0.1 might not - work using mstsc.exe. Instead, the - address - 127.0.0.2[:3389] has - to be used. + connection, the addresses localhost + and 127.0.0.1 might not work using + mstsc.exe. Instead, the address + 127.0.0.2[:3389] has to be used. @@ -181,16 +175,15 @@ -rdesktop -a 16 -N 1.2.3.4:3389 - - - Replace 1.2.3.4 with the - host IP address, and 3389 - with a different port, if necessary. The -a - 16 option requests a color depth of 16 bits - per pixel, which we recommend. For best performance, after - installation of the guest operating system, you should set - its display color depth to the same value. The - -N option enables use of - the NumPad keys. +$ rdesktop -a 16 -N 1.2.3.4:3389 + + + Replace 1.2.3.4 with the host IP address, + and 3389 with a different port, if + necessary. The option requests a + color depth of 16 bits per pixel, which we recommend. For + best performance, after installation of the guest operating + system, you should set its display color depth to the same + value. The option enables use of the + NumPad keys. @@ -207,15 +200,15 @@ If you run the KDE desktop, you can use - krdc, the KDE RDP viewer. A - typical command line is as follows: - - -krdc rdp://1.2.3.4:3389 - - - Replace 1.2.3.4 with the - host IP address, and 3389 - with a different port, if necessary. The "rdp://" prefix is - required with krdc to switch it into RDP mode. + krdc, the KDE RDP viewer. A typical + command line is as follows: + + +$ krdc rdp://1.2.3.4:3389 + + + Replace 1.2.3.4 with the host IP address, + and 3389 with a different port, if + necessary. The rdp:// prefix is required + with krdc to switch it into RDP mode. @@ -241,20 +234,20 @@ While any VM started from the VirtualBox Manager is capable of running virtual machines remotely, it is not convenient to have - to run the full-fledged GUI if you never want to have VMs - displayed locally in the first place. In particular, if you are - running server hardware whose only purpose is to host VMs, and - all your VMs are supposed to run remotely over VRDP, then it is - pointless to have a graphical user interface on the server at - all. This is especially true for Linux or Oracle Solaris hosts, - as the VirtualBox Manager comes with dependencies on the Qt and - SDL libraries. This is inconvenient if you would rather not have - the X Window system on your server at all. + to run the full GUI if you never want to have VMs displayed + locally in the first place. In particular, if you are running + server hardware whose only purpose is to host VMs, and all your + VMs are supposed to run remotely over VRDP, then it is pointless + to have a graphical user interface on the server at all. This is + especially true for Linux or Oracle Solaris hosts, as the + VirtualBox Manager comes with dependencies on the Qt and SDL + libraries. This is inconvenient if you would rather not have the + X Window system on your server at all. &product-name; therefore comes with a front-end called - VBoxHeadless, which produces no - visible output on the host at all, but still can optionally deliver - VRDP data. This front-end has no dependencies on the X Window system + VBoxHeadless, which produces no visible + output on the host at all, but still can optionally deliver VRDP + data. This front-end has no dependencies on the X Window system on Linux and Oracle Solaris hosts. @@ -262,15 +255,14 @@ - Before &product-name; 1.6, the headless server was called - VBoxVRDP. For the sake of - backwards compatibility, the &product-name; installation still - installs an executable with that name as well. + In legacy releases of &product-name;, the headless server was + called VBoxVRDP. For backwards + compatibility, the &product-name; installation still includes + an executable with that name. - To start a virtual machine with - VBoxHeadless, you have the - following options: + To start a virtual machine with VBoxHeadless, + you have the following options: @@ -282,12 +274,10 @@ -VBoxManage startvm "VM name" --type headless - - - The --type option causes - &product-name; to use - VBoxHeadless as the - front-end to the internal virtualization engine, instead of - the Qt front-end. +$ VBoxManage startvm VM-name --type headless + + + The option causes &product-name; to + use VBoxHeadless as the front-end to the + internal virtualization engine, instead of the Qt front-end. @@ -298,5 +288,5 @@ -VBoxHeadless --startvm <uuid|name> +VBoxHeadless --startvm uuid|vmname @@ -309,15 +299,14 @@ directly as a background process which has to be done explicitly when directly starting with - VBoxHeadless. The full - documentation of the command is in - . - - - - - - Start VBoxHeadless from the - VirtualBox Manager GUI, by pressing the Shift key when - starting a virtual machine or by selecting + VBoxHeadless. The full documentation of + the command is in . + + + + + + Start VBoxHeadless from the VirtualBox + Manager GUI, by pressing the Shift key when starting a + virtual machine or by selecting Headless Start from the Machine menu. @@ -328,12 +317,12 @@ - When you use the VBoxHeadless - command to start a VM, the VRDP server will be enabled according - to the VM configuration. You can override the VM's setting using - --vrde command line parameter. - To enable the VRDP server, start the VM as follows: - - -VBoxHeadless --startvm <uuid|name> --vrde on + When you use the VBoxHeadless command to + start a VM, the VRDP server will be enabled according to the VM + configuration. You can override the VM's setting using + command line parameter. To enable the + VRDP server, start the VM as follows: + + +VBoxHeadless --startvm uuid|vmname --vrde on @@ -341,5 +330,5 @@ -VBoxHeadless --startvm <uuid|name> --vrde off +VBoxHeadless --startvm uuid|vmname --vrde off @@ -348,5 +337,5 @@ -VBoxHeadless --startvm <uuid|name> --vrde config +VBoxHeadless --startvm uuid|vmname --vrde config @@ -354,5 +343,5 @@ -VBoxHeadless --startvm <uuid|name> +VBoxHeadless --startvm uuid|vmname @@ -398,6 +387,5 @@ A terminal connection to that host through which you can - access a command line, such as - ssh. + access a command line, such as ssh. @@ -428,14 +416,12 @@ - If you do not specify - --register, you will have - to manually use the registervm command - later. - - - - You do not need to specify - --ostype, but doing so - selects some sensible default values for certain VM + If you do not specify , you will + have to manually use the registervm + command later. + + + + You do not need to specify , but + doing so selects some sensible default values for certain VM parameters. For example, the RAM size and the type of the virtual network device. To get a complete list of supported @@ -564,5 +550,5 @@ supports this extension. On Linux and Oracle Solaris hosts, the &product-name; installation provides a suitable VRDP client - called rdesktop-vrdp. Recent versions of + called rdesktop-vrdp. Some versions of uttsc, a client tailored for the use with Sun Ray thin clients, also support accessing remote USB devices. RDP @@ -628,7 +614,7 @@ The default authentication library, - VBoxAuth, authenticates - against user credentials of the hosts. Depending on the - host platform, this means the following: + VBoxAuth, authenticates against user + credentials of the hosts. Depending on the host + platform, this means the following: @@ -637,6 +623,5 @@ - On Linux hosts, - VBoxAuth.so + On Linux hosts, VBoxAuth.so authenticates users against the host's PAM system. @@ -645,6 +630,5 @@ - On Windows hosts, - VBoxAuth.dll + On Windows hosts, VBoxAuth.dll authenticates users against the host's WinLogon system. @@ -654,6 +638,5 @@ - On Mac OS X hosts, - VBoxAuth.dylib + On Mac OS X hosts, VBoxAuth.dylib authenticates users against the host's directory service. @@ -675,10 +658,11 @@ An additional library called - VBoxAuthSimple performs + VBoxAuthSimple performs authentication against credentials configured in the - "extradata" section of a virtual machine's XML settings - file. This is probably the simplest way to get - authentication that does not depend on a running and - supported guest. The following steps are required: + extradata section of a virtual + machine's XML settings file. This is probably the + simplest way to get authentication that does not depend + on a running and supported guest. The following steps + are required: @@ -687,7 +671,6 @@ - Enable - VBoxAuthSimple with - the following command: + Enable VBoxAuthSimple with the + following command: @@ -701,9 +684,9 @@ -VBoxManage modifyvm "VM name" --vrdeauthtype external +VBoxManage modifyvm VM-name --vrdeauthtype external - Replace <vm> - with the VM name or UUID. + Replace VM-name with the + VM name or UUID. @@ -714,46 +697,36 @@ writing items into the machine's extradata. Since the XML machine settings file, into whose - extradata section - the password needs to be written, is a plain text - file, &product-name; uses hashes to encrypt - passwords. The following command must be used: + extradata section the password + needs to be written, is a plain text file, + &product-name; uses hashes to encrypt passwords. The + following command must be used: -VBoxManage setextradata "VM name" "VBoxAuthSimple/users/<user>" <hash> +VBoxManage setextradata VM-name "VBoxAuthSimple/users/user" hash - Replace <vm> - with the VM name or UUID, - <user> with - the user name who should be allowed to log in and - <hash> with - the encrypted password. As an example, to obtain the - hash value for the password - secret, you can use - the following command: + Replace VM-name with the + VM name or UUID, user + with the user name who should be allowed to log in + and hash with the + encrypted password. The following command example + obtains the hash value for the password + secret: -VBoxManage internalcommands passwordhash "secret" - - - This command will generate output similar to the - following: - - -2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b +$ VBoxManage internalcommands passwordhash "secret" +2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b You then use VBoxManage setextradata to store this value in the - machine's extradata - section. + machine's extradata section. As a combined example, to set the password for the - user john and the - machine My VM to - secret, use this - command: + user john and the machine + My VM to + secret, use this command: @@ -814,6 +787,6 @@ - RDP4 authentication was - used historically. With RDP4, the RDP client does not + RDP 4 authentication was + used historically. With RDP 4, the RDP client does not perform any checks in order to verify the identity of the server it connects to. Since user credentials can be @@ -825,9 +798,9 @@ - RDP5.1 authentication + RDP 5.1 authentication employs a server certificate for which the client possesses the public key. This way it is guaranteed that the server possess the corresponding private key. However, as this - hard-coded private key became public some years ago, RDP5.1 + hard-coded private key became public some years ago, RDP 5.1 authentication is also insecure. @@ -836,16 +809,17 @@ - RDP5.2 authentication uses - Enhanced RDP Security, which means that an external security - protocol is used to secure the connection. RDP4 and RDP5.1 - use Standard RDP Security. The VRDP server supports Enhanced - RDP Security with TLS protocol and, as a part of TLS - handshake, sends the server certificate to the client. - - - - The Security/Method VRDE - property sets the desired security method, which is used for - a connection. Valid values are as follows: + RDP 5.2 or later + authentication uses Enhanced RDP Security, which means that + an external security protocol is used to secure the + connection. RDP 4 and RDP 5.1 use Standard RDP Security. The + VRDP server supports Enhanced RDP Security with TLS protocol + and, as a part of the TLS handshake, sends the server + certificate to the client. + + + + The Security/Method VRDE property sets + the desired security method, which is used for a connection. + Valid values are as follows: @@ -875,10 +849,6 @@ - The OpenSSL library version determines which versions of - TLS are supported. The &product-name; clients include at - least Version 1.1.0 of the OpenSSL library. This library - supports TLS versions 1.0, 1.1, and 1.2. Some clients - might include newer versions of the OpenSSL library and - thus support additional TLS versions. + The version of OpenSSL used by &product-name; supports + TLS versions 1.0, 1.1, 1.2, and 1.3. @@ -891,13 +861,13 @@ -vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate" - - - If the Security/Method - property is set to either Negotiate or TLS, the TLS protocol - will be automatically used by the server, if the client - supports TLS. However, in order to use TLS the server must - possess the Server Certificate, the Server Private Key and - the Certificate Authority (CA) Certificate. The following +vboxmanage modifyvm VM-name --vrdeproperty "Security/Method=negotiate" + + + If the Security/Method property is set to + either Negotiate or TLS, the TLS protocol will be + automatically used by the server, if the client supports + TLS. However, in order to use TLS the server must possess + the Server Certificate, the Server Private Key and the + Certificate Authority (CA) Certificate. The following example shows how to generate a server certificate. @@ -939,11 +909,11 @@ -vboxmanage modifyvm "VM name" \ +vboxmanage modifyvm VM-name \ --vrdeproperty "Security/CACertificate=path/ca_cert.pem" -vboxmanage modifyvm "VM name" \ +vboxmanage modifyvm VM-name \ --vrdeproperty "Security/ServerCertificate=path/server_cert.pem" -vboxmanage modifyvm "VM name" \ +vboxmanage modifyvm VM-name \ --vrdeproperty "Security/ServerPrivateKey=path/server_key_private.pem" @@ -954,7 +924,6 @@ As the client that connects to the server determines what type of encryption will be used, with rdesktop, - the Linux RDP viewer, use the - -4 or - -5 options. + the Linux RDP viewer, use the or + options. @@ -978,5 +947,5 @@ -VBoxManage modifyvm "VM name" --vrdemulticon on +VBoxManage modifyvm VM-name --vrdemulticon on @@ -994,23 +963,21 @@ The RDP client can select the virtual monitor number to connect - to using the domain login - parameter (-d). If the - parameter ends with @ followed - by a number, &product-name; interprets this number as the screen - index. The primary guest screen is selected with - @1, the first secondary screen - is @2, and so on. - - - - The Microsoft RDP6 client does not let you specify a separate + to using the domain login parameter + (). If the parameter ends with + @ followed by a number, &product-name; + interprets this number as the screen index. The primary guest + screen is selected with @1, the first + secondary screen is @2, and so on. + + + + The Microsoft RDP 6 client does not let you specify a separate domain name. Instead, enter - domain\username in the - Username field. For example, - @2\name. - name must be supplied, and must - be the name used to log in if the VRDP server is set up to - require credentials. If it is not, you may use any text as the - username. + domain\username + in the Username field. For + example, @2\name. + name must be supplied, and must be + the name used to log in if the VRDP server is set up to require + credentials. If it is not, you may use any text as the username. @@ -1048,5 +1015,5 @@ -VBoxManage modifyvm "VM name" --vrdevideochannel on +VBoxManage modifyvm VM-name --vrdevideochannel on @@ -1057,5 +1024,5 @@ -VBoxManage modifyvm "VM name" --vrdevideochannelquality 75 +VBoxManage modifyvm VM-name --vrdevideochannelquality 75 @@ -1066,7 +1033,6 @@ - With &product-name; it is possible to disable display output, - mouse and keyboard input, audio, remote USB, or clipboard - individually in the VRDP server. + You can disable display output, mouse and keyboard input, audio, + remote USB, or clipboard individually in the VRDP server. @@ -1075,10 +1041,10 @@ -VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1 -VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1 -VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1 -VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableAudio=1 -VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableClipboard=1 -VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1 +$ VBoxManage modifyvm VM-name --vrdeproperty Client/DisableDisplay=1 +$ VBoxManage modifyvm VM-name --vrdeproperty Client/DisableInput=1 +$ VBoxManage modifyvm VM-name --vrdeproperty Client/DisableUSB=1 +$ VBoxManage modifyvm VM-name --vrdeproperty Client/DisableAudio=1 +$ VBoxManage modifyvm VM-name --vrdeproperty Client/DisableClipboard=1 +$ VBoxManage modifyvm VM-name --vrdeproperty Client/DisableUpstreamAudio=1 @@ -1087,5 +1053,5 @@ -VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay= +$ VBoxManage modifyvm VM-name --vrdeproperty Client/DisableDisplay= @@ -1174,13 +1140,12 @@ -VBoxManage modifyvm <targetvmname> --teleporter on --teleporterport <port> +VBoxManage modifyvm targetvmname --teleporter on --teleporterport port - where <targetvmname> is - the name of the virtual machine on the target host and - <port> is a TCP/IP port - number to be used on both the source and the target hosts. For - example, use 6000. See - . + targetvmname is the name of the + virtual machine on the target host and + port is a TCP/IP port number to be + used on both the source and the target hosts. For example, use + 6000. See . @@ -1201,16 +1166,15 @@ -VBoxManage controlvm <sourcevmname> teleport --host <targethost> --port <port> +VBoxManage controlvm sourcevmname teleport --host targethost --port port - where <sourcevmname> is - the name of the virtual machine on the source host, which is - the machine that is currently running. - <targethost> is the - host or IP name of the target host on which the machine is - waiting for the teleport request, and - <port> must be the same - number as specified in the command on the target host. See - . + where sourcevmname is the name of + the virtual machine on the source host, which is the machine + that is currently running. + targethost is the host or IP name + of the target host on which the machine is waiting for the + teleport request, and port must be + the same number as specified in the command on the target + host. See . @@ -1234,7 +1198,7 @@ capabilities are presented to the guest operating system. Advanced users can attempt to restrict these virtual CPU - capabilities with the VBoxManage modifyvm - --cpuid command. See - . + capabilities with the VBoxManage modifyvm + --cpuid command. See + . @@ -1244,4 +1208,3 @@ - Index: /trunk/doc/manual/en_US/user_Glossary.xml =================================================================== --- /trunk/doc/manual/en_US/user_Glossary.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Glossary.xml (revision 82350) @@ -138,6 +138,6 @@ application programming interfaces which can be accessed from various other programming languages and applications. - &product-name; makes use of COM both internally and externally to - provide a comprehensive API to 3rd party developers. + &product-name; makes use of COM both internally and externally + to provide a comprehensive API to 3rd party developers. @@ -221,7 +221,7 @@ "command line interface". In the context of &product-name;, we sometimes refer to the main graphical - VirtualBox program as the - "GUI", to differentiate it from the - VBoxManage interface. + VirtualBox program as the "GUI", to + differentiate it from the VBoxManage + interface. @@ -300,5 +300,5 @@ card. It is typically written in hexadecimal notation where the bytes are separated by colons, such as - 00:17:3A:5E:CB:08. + 00:17:3A:5E:CB:08. @@ -339,6 +339,6 @@ target IP addresses of network packets according to specific rules. Commonly employed by routers and firewalls to shield an - internal network from the Internet, &product-name; can use NAT to - easily share a host's physical networking hardware with its + internal network from the Internet, &product-name; can use NAT + to easily share a host's physical networking hardware with its virtual machines. See . @@ -382,6 +382,5 @@ Physical Address Extension. This enables access to more than 4 GB of RAM, even in 32-bit environments. See - . + . @@ -435,9 +434,9 @@ transferred in both directions. Typically graphics updates and audio are sent from the remote machine and keyboard and mouse - input events are sent from the client. An &product-name; extension - package by Oracle provides VRDP, an enhanced implementation of - the relevant standards which is largely compatible with - Microsoft's RDP implementation. See - for details. + input events are sent from the client. An &product-name; + extension package by Oracle provides VRDP, an enhanced + implementation of the relevant standards which is largely + compatible with Microsoft's RDP implementation. See + for details. @@ -537,5 +536,5 @@ UNIX versions for backing up data on tape. The file format is still widely used today. For example, with OVF archives using - an .ova file extension. See + an .ova file extension. See . @@ -561,6 +560,6 @@ and letters which can be computed dynamically and is guaranteed to be unique. Generally, it is used as a global - handle to identify entities. &product-name; makes use of UUIDs to - identify VMs, Virtual Disk Images (VDI files), and other + handle to identify entities. &product-name; makes use of UUIDs + to identify VMs, Virtual Disk Images (VDI files), and other entities. @@ -581,6 +580,6 @@ - Virtual Machine. A virtual computer that &product-name; enables - you to run on top of your actual hardware. See + Virtual Machine. A virtual computer that &product-name; + enables you to run on top of your actual hardware. See for details. @@ -612,6 +611,6 @@ VirtualBox Remote Desktop Extension. This interface is built - into &product-name; to allow &product-name; extension packages to - supply remote access to virtual machines. An &product-name; + into &product-name; to allow &product-name; extension packages + to supply remote access to virtual machines. An &product-name; extension package by Oracle provides VRDP support. See . @@ -689,7 +688,7 @@ infrastructure developed by the Mozilla browser project which is similar to Microsoft COM and enables applications to - provide a modular programming interface. &product-name; makes use - of XPCOM on Linux both internally and externally to provide a - comprehensive API to third-party developers. + provide a modular programming interface. &product-name; makes + use of XPCOM on Linux both internally and externally to + provide a comprehensive API to third-party developers. Index: /trunk/doc/manual/en_US/user_GuestAdditions.xml =================================================================== --- /trunk/doc/manual/en_US/user_GuestAdditions.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_GuestAdditions.xml (revision 82350) @@ -36,9 +36,8 @@ The &product-name; Guest Additions for all supported guest operating systems are provided as a single CD-ROM image file which - is called VBoxGuestAdditions.iso. - This image file is located in the installation directory of - &product-name;. To install the Guest Additions for a particular - VM, you mount this ISO file in your VM as a virtual CD-ROM and - install from there. + is called VBoxGuestAdditions.iso. This image + file is located in the installation directory of &product-name;. + To install the Guest Additions for a particular VM, you mount this + ISO file in your VM as a virtual CD-ROM and install from there. @@ -56,8 +55,9 @@ you with seamless mouse support. You will only have one mouse pointer and pressing the Host key is no longer required to - "free" the mouse from being captured by the guest OS. To make - this work, a special mouse driver is installed in the guest - that communicates with the "real" mouse driver on your host - and moves the guest mouse pointer accordingly. + free the mouse from being captured by the + guest OS. To make this work, a special mouse driver is + installed in the guest that communicates with the physical + mouse driver on your host and moves the guest mouse pointer + accordingly. @@ -71,7 +71,6 @@ folder, and &product-name; will make it available to the guest operating system as a network share, irrespective of whether - guest actually has a network. See - . + the guest actually has a network. See + . @@ -118,9 +117,9 @@ Generic host/guest communication channels. The Guest Additions enable you to control - and monitor guest execution. The "guest properties" provide a - generic string-based mechanism to exchange data bits between a - guest and a host, some of which have special meanings for - controlling and monitoring the guest. See - . + and monitor guest execution. The guest + properties provide a generic string-based mechanism + to exchange data bits between a guest and a host, some of + which have special meanings for controlling and monitoring the + guest. See . @@ -148,5 +147,5 @@ differs slightly, the time synchronization service attempts to gradually and smoothly adjust the guest time in small - increments to either "catch up" or "lose" time. When the + increments to either catch up or lose time. When the difference is too great, for example if a VM paused for hours or restored from saved state, the guest time is changed @@ -199,6 +198,6 @@ To disable this update check for the Guest Additions of a given virtual machine, set the value of its - /VirtualBox/GuestAdd/CheckHostVersion - guest property to 0. See + /VirtualBox/GuestAdd/CheckHostVersion guest + property to 0. See . @@ -343,11 +342,10 @@ - Select Mount CD/DVD-ROM + Select Optical Drives from the Devices menu in the virtual machine's menu bar and then - CD/DVD-ROM Image. This - displays the Virtual Media Manager, described in - . + Choose/Create a Disk + Image. This displays the Virtual Media Manager, + described in . @@ -358,6 +356,5 @@ Add and browse your host file system for the - VBoxGuestAdditions.iso - file. + VBoxGuestAdditions.iso file. @@ -368,6 +365,6 @@ On a Windows host, this file is in the &product-name; installation directory, usually in - C:\Program - files\Oracle\VirtualBox. + C:\Program + files\Oracle\VirtualBox. @@ -380,6 +377,5 @@ Show Package Contents. The file is located in the - Contents/MacOS - folder. + Contents/MacOS folder. @@ -388,7 +384,7 @@ On a Linux host, this file is in the - additions folder - where you installed &product-name;, usually - /opt/VirtualBox/. + additions folder where you + installed &product-name;, usually + /opt/VirtualBox/. @@ -397,7 +393,7 @@ On Oracle Solaris hosts, this file is in the - additions folder - where you installed &product-name;, usually - /opt/VirtualBox. + additions folder where you + installed &product-name;, usually + /opt/VirtualBox. @@ -409,7 +405,7 @@ In the Virtual Media Manager, select the ISO file and - click Select button. This - mounts the ISO file and presents it to your Windows guest - as a CD-ROM. + click the Add button. + This mounts the ISO file and presents it to your Windows + guest as a CD-ROM. @@ -422,6 +418,6 @@ Additions installation program from the Additions ISO. If the Autostart feature has been turned off, choose - VBoxWindowsAdditions.exe from - the CD/DVD drive inside the guest to start the installer. + VBoxWindowsAdditions.exe from the CD/DVD + drive inside the guest to start the installer. @@ -461,5 +457,5 @@ - + @@ -475,5 +471,5 @@ - + @@ -510,7 +506,7 @@ Installing the code signing certificates on a Windows guest can be done automatically. Use the - VBoxCertUtil.exe utility from - the cert folder on the Guest - Additions installation CD. + VBoxCertUtil.exe utility from the + cert folder on the Guest Additions + installation CD. @@ -536,6 +532,6 @@ Open a command line window on the guest and change to the - cert folder on the - &product-name; Guest Additions CD. + cert folder on the &product-name; + Guest Additions CD. @@ -577,7 +573,7 @@ driver needs to be installed. To select this driver by default, add the command line parameter - /with_wddm when invoking - the Windows Guest Additions installer. This is only required - for Vista and Windows 7. + /with_wddm when invoking the Windows + Guest Additions installer. This is only required for Vista + and Windows 7. @@ -616,8 +612,7 @@ a 32-bit system, you must use the appropriate platform installer. Use - VBoxWindowsAdditions-x86.exe - or - VBoxWindowsAdditions-amd64.exe - with the /extract parameter. + VBoxWindowsAdditions-x86.exe or + VBoxWindowsAdditions-amd64.exe with the + /extract parameter. @@ -657,5 +652,5 @@ - Redhat Enterprise Linux as of version 3 + Red Hat Enterprise Linux as of version 3 @@ -744,6 +739,5 @@ - Insert the - VBoxGuestAdditions.iso CD + Insert the VBoxGuestAdditions.iso CD file into your Linux guest's virtual CD-ROM drive, as described for a Windows guest in @@ -830,6 +824,6 @@ into the virtual CD-ROM drive as described above. Then run the installer for the current Guest Additions with the - uninstall parameter from the - path that the CD image is mounted on in the guest, as follows: + uninstall parameter from the path that the + CD image is mounted on in the guest, as follows: @@ -853,5 +847,5 @@ Replace - /opt/VBoxGuestAdditions-version + /opt/VBoxGuestAdditions-version with the correct Guest Additions installation directory. @@ -917,7 +911,6 @@ - Mount the - VBoxGuestAdditions.iso - file as your Oracle Solaris guest's virtual CD-ROM drive, + Mount the VBoxGuestAdditions.iso file + as your Oracle Solaris guest's virtual CD-ROM drive, exactly the same way as described for a Windows guest in \OS2. + the directory \OS2. We do not provide an automatic installer at this time. See the - readme.txt file in the CD-ROM - directory, which describes how to install the OS/2 Guest - Additions manually. + readme.txt file in the CD-ROM directory, + which describes how to install the OS/2 Guest Additions + manually. @@ -1027,6 +1020,6 @@ not require networking, only the Guest Additions. Shared folders are supported with Windows 2000 or later, Linux, and Oracle - Solaris guests. &product-name; release 6.0 includes experimental - support for Mac OS X and OS/2 guests. + Solaris guests. &product-name; includes experimental support for + Mac OS X and OS/2 guests. @@ -1104,6 +1097,6 @@ the VM is powered off. These can be created using a checkbox in the VirtualBox Manager, or by using the - --transient option of the - VBoxManage sharedfolder add command. + option of the VBoxManage + sharedfolder add command. @@ -1116,7 +1109,6 @@ read files on the host. By default, shared folders are read-write. Read-only folders can be created using a checkbox in the - VirtualBox Manager, or with the - --readonly option of the - VBoxManage sharedfolder add command. + VirtualBox Manager, or with the option + of the VBoxManage sharedfolder add command. @@ -1189,8 +1181,8 @@ - While vboxsvr is a fixed - name, note that vboxsrv - would also work, replace x: with - the drive letter that you want to use for the share, and + While vboxsvr is a fixed name, note that + vboxsrv would also work, replace + x: with the drive letter that you + want to use for the share, and sharename with the share name specified with VBoxManage. @@ -1207,5 +1199,5 @@ To mount a shared folder during boot, add the following - entry to /etc/fstab: + entry to /etc/fstab: @@ -1223,10 +1215,10 @@ Replace sharename, use a lowercase string, with the share name specified with - VBoxManage or the GUI. Replace - mountpoint with the path where - you want the share to be mounted on the guest, such as - /mnt/share. The usual mount - rules apply. For example, create this directory first if it - does not exist yet. + VBoxManage or the VirtualBox Manager. + Replace mountpoint with the path + where you want the share to be mounted on the guest, such as + /mnt/share. The usual mount rules + apply. For example, create this directory first if it does + not exist yet. @@ -1256,9 +1248,8 @@ This option sets the character set used for I/O operations. Note that on Linux guests, if the - iocharset option is not - specified, then the Guest Additions driver will attempt to - use the character set specified by the CONFIG_NLS_DEFAULT - kernel option. If this option is not set either, then UTF-8 - is used. + iocharset option is not specified, then + the Guest Additions driver will attempt to use the character + set specified by the CONFIG_NLS_DEFAULT kernel option. If + this option is not set either, then UTF-8 is used. @@ -1272,11 +1263,10 @@ The generic mount options, documented in the - mount manual page, apply - also. Especially useful are the options - uid, - gid and - mode, as they can allow - access by normal users in read/write mode, depending on the - settings, even if root has mounted the filesystem. + mount manual page, apply also. Especially + useful are the options uid, + gid and mode, as they + can allow access by normal users in read/write mode, + depending on the settings, even if root has mounted the + filesystem. @@ -1294,9 +1284,8 @@ As with Windows guests, shared folders can also be accessed - via UNC using \\VBoxSF\, - \\VBoxSvr\ or - \\VBoxSrv\ as the server - name and the shared folder name as - sharename. + via UNC using \\VBoxSF\, + \\VBoxSvr\ or + \\VBoxSrv\ as the server name and the + shared folder name as sharename. @@ -1332,6 +1321,6 @@ Windows and OS/2 guests. Search for a free drive letter, starting at - Z:. If all drive letters - are assigned, the folder is not mounted. + Z:. If all drive letters are assigned, + the folder is not mounted. @@ -1341,21 +1330,20 @@ Linux and Oracle Solaris guests. Folders are mounted under the - /media directory. The - folder name is normalized (no spaces, slashes or colons) and - is prefixed with sf_. + /media directory. The folder name is + normalized (no spaces, slashes or colons) and is prefixed + with sf_. For example, if you have a shared folder called - myfiles, it will appear as - /media/sf_myfiles in the - guest. + myfiles, it will appear as + /media/sf_myfiles in the guest. The guest properties - /VirtualBox/GuestAdd/SharedFolders/MountDir + /VirtualBox/GuestAdd/SharedFolders/MountDir and the more generic - /VirtualBox/GuestAdd/SharedFolders/MountPrefix + /VirtualBox/GuestAdd/SharedFolders/MountPrefix can be used to override the automatic mount directory and prefix. See . @@ -1369,6 +1357,6 @@ everyone in a Windows guest, including the guest user. For Linux and Oracle Solaris guests, access is restricted to members of - the group vboxsf and the - root user. + the group vboxsf and the + root user. @@ -1383,6 +1371,6 @@ &product-name; enables you to drag and drop content from the host - to the guest, and vice versa. For this to work the latest Guest - Additions must be installed on the guest. + to the guest, and vice versa. For this to work the latest version + of the Guest Additions must be installed on the guest. @@ -1439,5 +1427,5 @@
Drag and Drop Menu Options - + 3D acceleration with Windows guests requires Windows - 2000, Windows XP, Vista, or Windows 7. Apart from on - Windows 2000 guests, both OpenGL and Direct3D 8/9 are - supported on an experimental basis. + 2000 or later. Apart from on Windows 2000 guests, both + OpenGL and Direct3D 8/9 are supported on an experimental + basis. @@ -1692,5 +1680,5 @@ driver must be installed, which is available with the Guest Additions installation. The WDDM driver is not installed by - default for Vista and Windows 7 guest and must be + default for Vista and Windows 7 guests and must be manually selected in the Guest Additions installer by clicking No in the @@ -1701,48 +1689,21 @@ - The Aero theme is not enabled by default. To enable it, do the - following: - - - - - - - Windows Vista guests: - Right-click on the desktop and select - Personalize, then select - Windows Color and - Appearance in the - Personalization window. In - the Appearance Settings - dialog, select Windows Aero - and click OK. - - - - - - Windows 7 guests: - Right-click on the desktop and select - Personalize. Select any - Aero theme in the - Personalization window. - - - - - - - Technically, &product-name; implements this by installing an - additional hardware 3D driver inside your guest when the Guest - Additions are installed. This driver acts as a hardware 3D - driver and reports to the guest operating system that the - virtual hardware is capable of 3D hardware acceleration. When an - application in the guest then requests hardware acceleration - through the OpenGL or Direct3D programming interfaces, these are - sent to the host through a special communication tunnel - implemented by &product-name;, and then the - host performs the requested 3D operation - using the host's programming interfaces. + The Aero theme is not enabled by default on Windows. See your + Windows platform documentation for details of how to enable the + Aero theme. + + + + Technically, &product-name; implements 3D acceleration by + installing an additional hardware 3D driver inside the guest + when the Guest Additions are installed. This driver acts as a + hardware 3D driver and reports to the guest operating system + that the virtual hardware is capable of 3D hardware + acceleration. When an application in the guest then requests + hardware acceleration through the OpenGL or Direct3D programming + interfaces, these are sent to the host through a special + communication tunnel implemented by &product-name;. The + host then performs the requested 3D + operation using the host's programming interfaces. @@ -1806,5 +1767,5 @@ through a special communication tunnel implemented by &product-name;. On the host side, OpenGL is then used to - implement color space transformation and scaling + implement color space transformation and scaling. @@ -1829,5 +1790,5 @@ - Windows guests. Support was added in &product-name; 1.5. + Windows guests. @@ -1836,5 +1797,5 @@ Supported Linux or Oracle Solaris guests running the X Window - System. Support was added with &product-name; 1.6. + System. @@ -1851,5 +1812,5 @@
Seamless Windows on a Host Desktop - + @@ -1918,7 +1879,6 @@ version of the Guest Additions, users that are currently logged into the guest OS, network statistics and more. These predefined - properties are all prefixed with - /VirtualBox/ and organized into a - hierarchical tree of keys. + properties are all prefixed with /VirtualBox/ + and organized into a hierarchical tree of keys. @@ -1940,5 +1900,5 @@ $ VBoxManage guestproperty enumerate "Windows Vista III" VirtualBox Command Line Management Interface Version version-number -(C) 2005-2018 Oracle Corporation +(C) 2005-2019 Oracle Corporation All rights reserved. @@ -1997,10 +1957,10 @@ To query the value of a single property, use the - get subcommand as follows: + get subcommand as follows: $ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product" VirtualBox Command Line Management Interface Version version-number -(C) 2005-2018 Oracle Corporation +(C) 2005-2019 Oracle Corporation All rights reserved. @@ -2009,13 +1969,12 @@ To add or change guest properties from the guest, use the tool - VBoxControl. This tool is - included in the Guest Additions of &product-name; 2.2 or later. - When started from a Linux guest, this tool requires root - privileges for security reasons: + VBoxControl. This tool is included in the Guest + Additions. When started from a Linux guest, this tool requires + root privileges for security reasons. $ sudo VBoxControl guestproperty enumerate VirtualBox Guest Additions Command Line Management Interface Version version-number -(C) 2005-2018 Oracle Corporation +(C) 2005-2019 Oracle Corporation All rights reserved. @@ -2036,10 +1995,9 @@ - The properties - /VirtualBox/HostInfo/VBoxVer, - /VirtualBox/HostInfo/VBoxVerExt - or /VirtualBox/HostInfo/VBoxRev - can be waited on to detect that the VM state was restored from - saved state or snapshot: + The properties /VirtualBox/HostInfo/VBoxVer, + /VirtualBox/HostInfo/VBoxVerExt or + /VirtualBox/HostInfo/VBoxRev can be waited on + to detect that the VM state was restored from saved state or + snapshot: @@ -2048,7 +2006,7 @@ Similarly the - /VirtualBox/HostInfo/ResumeCounter - can be used to detect that a VM was resumed from the paused - state or saved state. + /VirtualBox/HostInfo/ResumeCounter can be + used to detect that a VM was resumed from the paused state or + saved state. @@ -2070,5 +2028,5 @@
Guest Control File Manager - + - The Guest Additions enable starting of applications inside a VM - from the host system. - - - - For this to work, the application needs to be installed inside the + The Guest Additions enable starting of applications inside a guest + VM from the host system. This feature can be used to automate + deployment of software within the guest. + + + + For this to work, the application needs to be installed on the guest. No additional software needs to be installed on the host. Additionally, text mode output to stdout and stderr can be shown @@ -2179,13 +2138,8 @@ - This feature can be used to automate deployment of software within - the guest. - - - The Guest Additions for Windows allow for automatic updating. This - applies for already installed Guest Additions version 4.0 or - later. Also, copying files from host to the guest as well as - remotely creating guest directories is available. + applies for already installed Guest Additions versions. Also, + copying files from host to the guest as well as remotely creating + guest directories is available. @@ -2234,6 +2188,7 @@ Memory ballooning does not work with large pages enabled. To turn off large pages support for a VM, run - VBoxManage modifyvm <VM name> - --largepages off + VBoxManage modifyvm + vmname --largepages + off @@ -2303,7 +2258,7 @@ By default, no balloon memory is allocated. This is a VM - setting, like other modifyvm - settings, and therefore can only be set while the machine is - shut down. See modifyvm settings, and + therefore can only be set while the machine is shut down. See + . @@ -2341,14 +2296,13 @@ efficiently Page Fusion can reduce the amount of host memory that is in use. It therefore works best if all VMs on a host run - identical operating systems, such as Windows XP Service Pack 2. - Instead of having a complete copy of each operating system in - each VM, Page Fusion identifies the identical memory pages in - use by these operating systems and eliminates the duplicates, - sharing host memory between several machines. This is called - deduplication. If a VM tries to modify a - page that has been shared with other VMs, a new page is - allocated again for that VM with a copy of the shared page. This - is called copy on write. All this is fully - transparent to the virtual machine. + identical operating systems. Instead of having a complete copy + of each operating system in each VM, Page Fusion identifies the + identical memory pages in use by these operating systems and + eliminates the duplicates, sharing host memory between several + machines. This is called deduplication. If + a VM tries to modify a page that has been shared with other VMs, + a new page is allocated again for that VM with a copy of the + shared page. This is called copy on write. + All this is fully transparent to the virtual machine. @@ -2411,11 +2365,10 @@ You can observe Page Fusion operation using some metrics. - RAM/VMM/Shared shows the total - amount of fused pages, whereas the per-VM metric - Guest/RAM/Usage/Shared will - return the amount of fused memory for a given VM. See - for information on - how to query metrics. + RAM/VMM/Shared shows the total amount of + fused pages, whereas the per-VM metric + Guest/RAM/Usage/Shared will return the amount + of fused memory for a given VM. See + for information on how to + query metrics. Index: /trunk/doc/manual/en_US/user_Installation.xml =================================================================== --- /trunk/doc/manual/en_US/user_Installation.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Installation.xml (revision 82350) @@ -26,12 +26,10 @@ For the various versions of Windows that are supported as host operating systems, please refer to - . - - - - In addition, Windows Installer 1.1 or later must be present on - your system. This should be the case if you have all recent - Windows updates installed. + . + + + + In addition, Windows Installer must be present on your system. + This should be the case for all supported Windows platforms. @@ -51,6 +49,5 @@ - By double-clicking on the executable file, which contains - both 32-bit and 64-bit architectures. + By double-clicking on the executable file. @@ -64,10 +61,10 @@ - This will extract both installers into a temporary - directory, along with .MSI files. Run the following command - to to perform the installation: - - -msiexec /i VirtualBox-<version>-<revision>-MultiArch_<x86|amd64>.msi + This will extract the installer into a temporary directory, + along with the .MSI file. Run the following command to + perform the installation: + + +msiexec /i VirtualBox-<version>-<revision>-Win.msi @@ -114,12 +111,11 @@ See, for example: - http://www.python.org/download/windows/. + . - Python version at least 2.6 is required. Since - &product-name; 5.1, Python 3 is also supported. + Python version at least 2.6 is required. Python 3 is also + supported. @@ -137,5 +133,5 @@ - The installer will create a &product-name; group in the Windows + The installer will create an &product-name; group in the Windows Start menu, which enables you to launch the application and access its documentation. @@ -152,5 +148,5 @@ Then, run either of the following commands on the extracted .MSI - files. This will install &product-name; only for the current + file. This will install &product-name; only for the current user. @@ -158,11 +154,10 @@ VirtualBox.exe -msiparams ALLUSERS=2 -msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi ALLUSERS=2 +msiexec /i VirtualBox-<version>-Win.msi ALLUSERS=2 If you do not want to install all features of &product-name;, - you can set the optional - ADDLOCAL parameter to - explicitly name the features to be installed. The following + you can set the optional ADDLOCAL parameter + to explicitly name the features to be installed. The following features are available: @@ -248,11 +243,4 @@ Python support - - - - Python version at least 2.6 is required. Since - &product-name; 5.1, Python 3 is also supported. - - @@ -267,24 +255,26 @@ VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB -msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi ADDLOCAL=VBoxApplication,VBoxUSB +msiexec /i VirtualBox-<version>-Win.msi ADDLOCAL=VBoxApplication,VBoxUSB The user is able to choose between NDIS5 and NDIS6 host network filter drivers during the installation. This is done using a - command line parameter, - NETWORKTYPE. The NDIS6 driver - is default for Windows Vista and later. For older Windows - versions, the installer will automatically select the NDIS5 - driver and this cannot be changed. For Windows Vista and later - the user can force an install of the legacy NDIS5 host network - filter driver by using - NETWORKTYPE=NDIS5. For example, - to install the NDIS5 driver on Windows 7 use either of the - following commands: + command line parameter, NETWORKTYPE. The + NDIS6 driver is the default for most supported Windows hosts. + For some legacy Windows versions, the installer will + automatically select the NDIS5 driver and this cannot be + changed. + + + + You can force an install of the legacy NDIS5 host network filter + driver by specifying NETWORKTYPE=NDIS5. For + example, to install the NDIS5 driver on Windows 7 use either of + the following commands: VirtualBox.exe -msiparams NETWORKTYPE=NDIS5 -msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi NETWORKTYPE=NDIS5 +msiexec /i VirtualBox-<version>-Win;.msi NETWORKTYPE=NDIS5 @@ -326,5 +316,5 @@ VirtualBox.exe -msiparams NAME=VALUE [...] -msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi NAME=VALUE [...] +msiexec /i VirtualBox-<version>-Win.msi NAME=VALUE [...] @@ -345,6 +335,6 @@ - Set to 1 to enable, - 0 to disable. Default is 1. + Set to 1 to enable, 0 + to disable. Default is 1. @@ -361,6 +351,6 @@ - Set to 1 to enable, - 0 to disable. Default is 1. + Set to 1 to enable, 0 + to disable. Default is 1. @@ -379,6 +369,6 @@ - Set to 1 to enable, - 0 to disable. Default is 1. + Set to 1 to enable, 0 + to disable. Default is 1. @@ -395,6 +385,6 @@ - Set to 1 to enable, - 0 to disable. Default is 1. + Set to 1 to enable, 0 + to disable. Default is 1. @@ -416,6 +406,6 @@ For Mac OS X hosts, &product-name; ships in a - dmg disk image file. Perform - the following steps to install on a Mac OS X host: + dmg disk image file. Perform the following + steps to install on a Mac OS X host: @@ -424,6 +414,6 @@ - Double-click on the dmg - file, to mount the contents. + Double-click on the dmg file, to mount + the contents. @@ -432,13 +422,20 @@ A window opens, prompting you to double-click on the - VirtualBox.pkg installer - file displayed in that window. - - - - - - This will start the installer, which enables you to select - where to install &product-name;. + VirtualBox.pkg installer file displayed + in that window. + + + + + + This starts the installer, which enables you to select where + to install &product-name;. + + + + + + An &product-name; icon is added to the + Applications folder in the Finder. @@ -446,9 +443,4 @@ - - After installation, you can find an &product-name; icon in the - "Applications" folder in the Finder. - - @@ -459,6 +451,6 @@ To uninstall &product-name;, open the disk image - dmg file and double-click on - the uninstall icon shown. + dmg file and double-click on the uninstall + icon shown. @@ -475,7 +467,7 @@ - Mount the dmg disk image file, - as described in the installation procedure, or use the following - command line: + Mount the dmg disk image file, as described + in the installation procedure, or use the following command + line: @@ -502,10 +494,9 @@ For the various versions of Linux that are supported as host - operating systems, see . - - - - You will need to install the following packages on your Linux + operating systems, see . + + + + You may need to install the following packages on your Linux system before starting the installation. Some systems will do this for you automatically when you install &product-name;. @@ -523,5 +514,5 @@ SDL 1.2.7 or later. This graphics library is typically - called libsdl or similar. + called libsdl or similar. @@ -533,7 +524,7 @@ These packages are only required if you want to run the &product-name; graphical user interfaces. In particular, - VirtualBox, the graphical - VirtualBox Manager, requires both Qt and SDL. If you only want - to run VBoxHeadless, neither Qt nor SDL are + VirtualBox, the graphical VirtualBox + Manager, requires both Qt and SDL. If you only want to run + VBoxHeadless, neither Qt nor SDL are required. @@ -544,19 +535,21 @@ - The &product-name; Driver Modules + The &product-name; Kernel Modules In order to run other operating systems in virtual machines alongside your main operating system, &product-name; needs to - integrate very tightly into the system. To do this it installs a - driver module called vboxdrv - which does a lot of that work into the system kernel, which is - the part of the operating system which controls your processor - and physical hardware. Without this kernel module, you can still - use the VirtualBox Manager to configure virtual machines, but - they will not start. It also installs network drivers called - vboxnetflt and - vboxnetadp which enable virtual - machines to make more use of your computer's network + integrate very tightly with your system. To do this it installs + a driver module called vboxdrv into the + system kernel. The kernel is the part of the operating system + which controls your processor and physical hardware. Without + this kernel module, you can still use the VirtualBox Manager to + configure virtual machines, but they will not start. + + + + Network drivers called vboxnetflt and + vboxnetadp are also installed. They enable + virtual machines to make more use of your computer's network capabilities and are needed for any virtual machine networking beyond the basic NAT mode. @@ -565,21 +558,53 @@ Since distributing driver modules separately from the kernel is - not something which Linux supports well, the install process - creates the modules on the system where they will be used. This - usually means first installing software packages from the - distribution which are needed for the build process. Normally, - these will be the GNU compiler (GCC), GNU Make (make) and - packages containing header files for your kernel, as well as - making sure that all system updates are installed and that the - system is running the most up-to-date kernel included in the - distribution. The running kernel and the header files - must be updated to matching versions. The following - list includes some instructions for common distributions. For - most of them you may want to start by finding the version name + not something which Linux supports well, the &product-name; + install process creates the modules on the system where they + will be used. This means that you may need to install some + software packages from the distribution which are needed for the + build process. Required packages may include the following: + + + + + + + GNU compiler (GCC) + + + + + + GNU Make (make) + + + + + + Kernel header files + + + + + + + Also ensure that all system updates have been installed and that + your system is running the most up-to-date kernel for the + distribution. + + + + + The running kernel and the kernel header files must be updated + to matching versions. + + + + + The following list includes some details of the required files + for some common distributions. Start by finding the version name of your kernel, using the command uname -r in - a terminal. The instructions assume that you have not changed - too much from the original installation, particularly not - installed a different kernel type. If you have, then you will - need to determine yourself what to set up. + a terminal. The list assumes that you have not changed too much + from the original installation, in particular that you have not + installed a different kernel type. @@ -590,36 +615,35 @@ With Debian and Ubuntu-based distributions, you must install the correct version of the - linux-headers, usually - whichever of - linux-headers-generic, - linux-headers-amd64, - linux-headers-i686 or - linux-headers-i686-pae best - matches the kernel version name. Also, the - linux-kbuild package if it - exists. Basic Ubuntu releases should have the correct - packages installed by default. - - - - - - On Fedora, Redhat, Oracle Linux and many other RPM-based + linux-headers, usually whichever of + linux-headers-generic, + linux-headers-amd64, + linux-headers-i686 or + linux-headers-i686-pae best matches the + kernel version name. Also, the + linux-kbuild package if it exists. + Basic Ubuntu releases should have the correct packages + installed by default. + + + + + + On Fedora, Red Hat, Oracle Linux and many other RPM-based systems, the kernel version sometimes has a code of letters or a word close to the end of the version name. For example - "uek" for the Oracle Enterprise kernel or "default" or - "desktop" for the standard SUSE kernels. In this case, the - package name is - kernel-uek-devel or - equivalent. If there is no such code, it is usually - kernel-devel. - - - - - - On older SUSE and openSUSE Linux, you must install the - kernel-source and - kernel-syms packages. + "uek" for the Oracle Unbreakable Enterprise Kernel or + "default" or "desktop" for the standard kernels. In this + case, the package name is + kernel-uek-devel or equivalent. If + there is no such code, it is usually + kernel-devel. + + + + + + On some SUSE and openSUSE Linux versions, you may need to + install the kernel-source and + kernel-syms packages. @@ -635,4 +659,49 @@ rcvboxdrv setup + + + Kernel Modules and UEFI Secure Boot + + + If you are running on a system using UEFI (Unified Extensible + Firmware Interface) Secure Boot, you may need to sign the + following kernel modules before you can load them: + + + + + + + vboxdrv + + + + + + vboxnetadp + + + + + + vboxnetflt + + + + + + vboxpci + + + + + + + See your system documentation for details of the kernel module + signing process. + + + + @@ -645,22 +714,20 @@ native to various common Linux distributions. See . In addition, there is an - alternative generic installer (.run) which should work on most - Linux distributions. The generic installer packages are built on - EL5 systems and thus require reasonably old versions of glibc, - such as version 2.5, and other system libraries. + alternative generic installer (.run) which you can use on + supported Linux distributions. - Installing &product-name; from a Debian/Ubuntu Package + Installing &product-name; from a Debian or Ubuntu Package Download the appropriate package for your distribution. The - following examples assume that you are installing to a 32-bit - Ubuntu Wily system. Use dpkg - to install the Debian package,as follows: - - -sudo dpkg -i virtualbox-5.0_version-number_Ubuntu_wily_i386.deb + following example assumes that you are installing to a 64-bit + Ubuntu Xenial system. Use dpkg to install + the Debian package,as follows: + + +sudo dpkg -i virtualbox-version-number_Ubuntu_xenial_amd64.deb @@ -669,10 +736,9 @@ successful you will be shown a warning and the package will be left unconfigured. Look at - /var/log/vbox-install.log to - find out why the compilation failed. You may have to install - the appropriate Linux kernel headers, see - . After - correcting any problems, run the following command: + /var/log/vbox-install.log to find out why + the compilation failed. You may have to install the + appropriate Linux kernel headers, see + . After correcting any + problems, run the following command: @@ -687,7 +753,6 @@ module was successfully built, the installation script will attempt to load that module. If this fails, please see - - for further information. + for + further information. @@ -716,6 +781,6 @@ Unpacks the application files to the target directory - /opt/VirtualBox/, which - cannot be changed. + /opt/VirtualBox/, which cannot be + changed. @@ -724,14 +789,13 @@ Builds and installs the &product-name; kernel modules: - vboxdrv, - vboxnetflt, and - vboxnetadp. - - - - - - Creates /sbin/rcvboxdrv, - an init script to start the &product-name; kernel module. + vboxdrv, vboxnetflt, + and vboxnetadp. + + + + + + Creates /sbin/rcvboxdrv, an init + script to start the &product-name; kernel module. @@ -740,14 +804,12 @@ Creates a new system group called - vboxusers. - - - - - - Creates symbolic links in - /usr/bin to a shell - script - /opt/VirtualBox/VBox + vboxusers. + + + + + + Creates symbolic links in /usr/bin to + a shell script /opt/VirtualBox/VBox which does some sanity checks and dispatches to the actual executables: VirtualBox, @@ -761,8 +823,8 @@ Creates - /etc/udev/rules.d/60-vboxdrv.rules, - a description file for udev, if that is present, which - makes the USB devices accessible to all users in the - vboxusers group. + /etc/udev/rules.d/60-vboxdrv.rules, a + description file for udev, if that is present, which makes + the USB devices accessible to all users in the + vboxusers group. @@ -771,5 +833,5 @@ Writes the installation directory to - /etc/vbox/vbox.cfg. + /etc/vbox/vbox.cfg. @@ -779,7 +841,6 @@ The installer must be executed as root with either - install or - uninstall as the first - parameter. For example: + install or uninstall as + the first parameter. For example: @@ -795,7 +856,7 @@ Add every user who needs to access USB devices from a - VirtualBox guests to the group - vboxusers. Either use the GUI - user management tools or run the following command as root: + VirtualBox guests to the group vboxusers. + Either use the OS user management tools or run the following + command as root: @@ -811,7 +872,7 @@ groups command and add all these groups in a comma-separated list to the command line after the - option. For example: - usermod -G group1,group2,vboxusers - username. + option. For example: usermod -G + group1,group2,vboxusers + username. @@ -833,9 +894,8 @@ This will unpack all the files needed for installation in the - directory install under the - current directory. The &product-name; application files are - contained in - VirtualBox.tar.bz2 which you - can unpack to any directory on your system. For example: + directory install under the current + directory. The &product-name; application files are contained + in VirtualBox.tar.bz2 which you can + unpack to any directory on your system. For example: @@ -852,7 +912,6 @@ The sources for &product-name;'s kernel module are provided in - the src directory. To build - the module, change to the directory and use the following - command: + the src directory. To build the module, + change to the directory and use the following command: @@ -878,8 +937,7 @@ you how to create the device node, depending on your Linux system. The procedure is slightly different for a classical - Linux setup with a /dev - directory, a system with the now deprecated - devfs and a modern Linux system with - udev. + Linux setup with a /dev directory, a + system with the now deprecated devfs and a + modern Linux system with udev. @@ -893,7 +951,7 @@ - Note that the /dev/vboxdrv - kernel module device node must be owned by root:root and must - be read/writable only for the user. + Note that the /dev/vboxdrv kernel module + device node must be owned by root:root and must be + read/writable only for the user. @@ -908,5 +966,5 @@ This example assumes you installed &product-name; to the - /opt/VirtualBox directory. + /opt/VirtualBox directory. @@ -971,6 +1029,6 @@ perform this task. To prevent any user interaction during installation, default values can be defined. A file - vboxconf can contain the - following debconf settings: + vboxconf can contain the following debconf + settings: @@ -1008,7 +1066,6 @@ The RPM format does not provide a configuration system comparable to the debconf system. See - for how to set - some common installation options provided by &product-name;. + for how to set some + common installation options provided by &product-name;. @@ -1022,7 +1079,7 @@ To configure the installation process for .deb and .rpm packages, you can create a response file named - /etc/default/virtualbox. The - automatic generation of the udev rule can be prevented with - the following setting: + /etc/default/virtualbox. The automatic + generation of the udev rule can be prevented with the + following setting: @@ -1038,7 +1095,6 @@ If the following line is specified, the package installer will - not try to build the vboxdrv - kernel module if no module fitting the current kernel was - found. + not try to build the vboxdrv kernel module + if no module fitting the current kernel was found. @@ -1055,10 +1111,9 @@ The Linux installers create the system user group - vboxusers during installation. - Any system user who is going to use USB devices from - &product-name; guests must be a member of that group. A user can - be made a member of the group - vboxusers through the GUI - user/group management or using the following command: + vboxusers during installation. Any system + user who is going to use USB devices from &product-name; guests + must be a member of that group. A user can be made a member of + the group vboxusers either by using the + desktop user and group tools, or with the following command: @@ -1072,5 +1127,5 @@ - The easiest way to start a &product-name; program is by running + The easiest way to start an &product-name; program is by running the program of your choice (VirtualBox, VBoxManage, or @@ -1084,18 +1139,17 @@ if you wish to execute &product-name; without installing it first. You should start by compiling the - vboxdrv kernel module and - inserting it into the Linux kernel. &product-name; consists of a - service daemon, VBoxSVC, and - several application programs. The daemon is automatically - started if necessary. All &product-name; applications will - communicate with the daemon through UNIX local domain sockets. - There can be multiple daemon instances under different user - accounts and applications can only communicate with the daemon - running under the user account as the application. The local - domain socket resides in a subdirectory of your system's - directory for temporary files called - .vbox-<username>-ipc. In - case of communication problems or server startup problems, you - may try to remove this directory. + vboxdrv kernel module and inserting it into + the Linux kernel. &product-name; consists of a service daemon, + VBoxSVC, and several application programs. + The daemon is automatically started if necessary. All + &product-name; applications will communicate with the daemon + through UNIX local domain sockets. There can be multiple daemon + instances under different user accounts and applications can + only communicate with the daemon running under the user account + as the application. The local domain socket resides in a + subdirectory of your system's directory for temporary files + called .vbox-<username>-ipc. In case + of communication problems or server startup problems, you may + try to remove this directory. @@ -1119,6 +1173,5 @@ For the specific versions of Oracle Solaris that are supported as - host operating systems, see . + host operating systems, see . @@ -1137,12 +1190,15 @@ &product-name; is available as a standard Oracle Solaris - package. Download the &product-name; SunOS package which - includes the 64-bit versions of &product-name;. The + package. Download the &product-name; SunOS package, which + includes the 64-bit version of &product-name;. The installation must be performed as root and from the global - zone as the &product-name; installer loads kernel - drivers which cannot be done from non-global zones. To verify - which zone you are currently in, execute the - zonename command. Execute the following - commands: + zone. This is because the &product-name; installer + loads kernel drivers, which cannot be done from non-global + zones. To verify which zone you are currently in, execute the + zonename command. + + + + To start installation, run the following commands: @@ -1150,7 +1206,6 @@ - The &product-name; kernel package is no longer a separate - package and has been integrated into the main package. Install - the &product-name; package as follows: + The &product-name; kernel package is integrated into the main + package. Install the &product-name; package as follows: @@ -1172,7 +1227,7 @@ Once the postinstall script has been executed your installation is now complete. You may now safely delete the uncompressed - package and autoresponse files - from your system. &product-name; is installed in - /opt/VirtualBox. + package and autoresponse files from your + system. &product-name; is installed in + /opt/VirtualBox. @@ -1192,11 +1247,11 @@ The installer creates the system user group - vboxuser during installation - for Oracle Solaris hosts that support the USB features required - by &product-name;. Any system user who is going to use USB - devices from &product-name; guests must be a member of this - group. A user can be made a member of this group through the GUI - user/group management or at the command line by executing as - root: + vboxuser during installation for Oracle + Solaris hosts that support the USB features required by + &product-name;. Any system user who is going to use USB devices + from &product-name; guests must be a member of this group. A + user can be made a member of this group either by using the + desktop user and group tools or by running the following command + as root: @@ -1204,7 +1259,8 @@ - Note that adding an active user to that group will require that - user to log out and back in again. This should be done manually - after successful installation of the package. + Note that adding an active user to the + vboxuser group will require the user to log + out and then log in again. This should be done manually after + successful installation of the package. @@ -1216,5 +1272,5 @@ - The easiest way to start a &product-name; program is by running + The easiest way to start an &product-name; program is by running the program of your choice (VirtualBox, VBoxManage, or @@ -1226,7 +1282,6 @@ Alternatively, you can directly invoke the required programs - from /opt/VirtualBox. Using the - links provided is easier as you do not have to enter the full - path. + from /opt/VirtualBox. Using the links + provided is easier as you do not have to enter the full path. @@ -1256,12 +1311,4 @@ - - If you are uninstalling &product-name; version 3.0 or lower, you - need to remove the &product-name; kernel interface package, as - follows: - - -pkgrm SUNWvboxkern - @@ -1273,13 +1320,12 @@ To perform a non-interactive installation of &product-name; there is a response file named - autoresponse, that the - installer will use for responses to inputs rather than ask them - from you. - - - - Extract the tar.gz package as described in the normal - installation instructions. Then open a root terminal session and - run the following command: + autoresponse. The installer uses this for + responses to inputs, rather than prompting the user. + + + + Extract the tar.gz package as described in + . Then open a root + terminal session and run the following command: @@ -1306,16 +1352,15 @@ -zonecfg -z vboxzone - - - Replace "vboxzone" with the name of the zone where you intend to - run &product-name;. - - - - Usezonecfg to add the - device resource and - match properties to the zone, - as follows: +zonecfg -z vboxzone + + + Replace vboxzone with the name of the + zone where you intend to run &product-name;. + + + + Use zonecfg to add the + device resource and match + properties to the zone, as follows: @@ -1329,18 +1374,15 @@ - If you are running &product-name; 2.2.0 or above on Oracle - Solaris 11 or above, you may also add a device for - /dev/vboxusbmon, similar to - that shown above. This does not apply to Oracle Solaris 10 - hosts, due to lack of USB support. + On Oracle Solaris 11 or later, you may also add a device for + /dev/vboxusbmon, similar to that shown + above. If you are not using sparse root zones, you will need to - loopback mount /opt/VirtualBox - from the global zone into the non-global zone at the same path. - This is specified below using the - dir attribute and the - special attribute. For example: + loopback mount /opt/VirtualBox from the + global zone into the non-global zone at the same path. This is + specified below using the dir attribute and + the special attribute. For example: @@ -1353,7 +1395,6 @@ - Reboot the zone using zoneadm - and you should be able to run &product-name; from within the - configured zone. + Reboot the zone using zoneadm and you should + be able to run &product-name; from within the configured zone. Index: /trunk/doc/manual/en_US/user_Introduction.xml =================================================================== --- /trunk/doc/manual/en_US/user_Introduction.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Introduction.xml (revision 82350) @@ -184,5 +184,5 @@ OS). This is the OS that is running inside the virtual machine. Theoretically, &product-name; can run any x86 - OS. such as DOS, Windows, OS/2, FreeBSD, and OpenBSD. But to + OS such as DOS, Windows, OS/2, FreeBSD, and OpenBSD. But to achieve near-native performance of the guest code on your machine, we had to go through a lot of optimizations that are @@ -203,24 +203,24 @@ is the special environment that &product-name; creates for your guest OS while it is running. In other words, you run - your guest OS in a VM. Normally, a VM - will be shown as a window on your computer's desktop, but - depending on which of the various frontends of &product-name; - you use, it can be displayed in full screen mode or remotely - on another computer. - - - - In a more abstract way, internally, &product-name; thinks of a - VM as a set of parameters that determine its behavior. They - include hardware settings, such as: how much memory the VM - should have, what hard disks &product-name; should virtualize - through which container files, what CDs are mounted. They also - include state information, such as: whether the VM is - currently running, saved, if the VM has snapshots. These - settings are mirrored in the VirtualBox Manager window, as - well as the VBoxManage command. See - . In other words, a VM is also - what you can see in its - Settings dialog. + your guest OS in a VM. Normally, a VM is + shown as a window on your computer's desktop. Depending on + which of the various frontends of &product-name; you use, the + VM might be shown in full screen mode or remotely on another + computer. + + + + Internally, &product-name; treats a VM as a set of parameters + that specify its behavior. Some parameters describe hardware + settings, such as the amount of memory and number of CPUs + assigned. Other parameters describe the state information, + such as whether the VM is running or saved. + + + + You can view these VM settings in the VirtualBox Manager + window, the Settings dialog, + and by running the VBoxManage command. See + . @@ -287,8 +287,8 @@ - For users of &oci; the functionality extends to exporting - and importing virtial machines to and from the cloud. This - simplifies development of applications and deployment to - the production environment. See + For users of &oci; the functionality extends to exporting and + importing virtual machines to and from the cloud. This + simplifies development of applications and deployment to the + production environment. See . @@ -310,7 +310,8 @@ - In particular, Guest Additions provide for "shared folders", - which let you access files from the host system from within a - guest machine. See . + In particular, Guest Additions provide for shared + folders, which let you access files on the host + system from within a guest machine. See + . @@ -319,5 +320,5 @@ Great hardware support. Among - others, &product-name; supports the following: + other features, &product-name; supports the following: @@ -350,11 +351,11 @@ devices, among them many devices that are typically provided by other virtualization platforms. That includes - IDE, SCSI and SATA hard disk controllers, several virtual + IDE, SCSI, and SATA hard disk controllers, several virtual network cards and sound cards, virtual serial and parallel ports and an Input/Output Advanced Programmable Interrupt - Controller (I/O APIC), which is found in many modern PC - systems. This eases cloning of PC images from real - machines and importing of third-party virtual machines - into &product-name;. + Controller (I/O APIC), which is found in many computer + systems. This enables easy cloning of disk images from + real machines and importing of third-party virtual + machines into &product-name;. @@ -364,12 +365,13 @@ Full ACPI support. The Advanced Configuration and Power Interface (ACPI) is fully - supported by &product-name;. This eases cloning of PC - images from real machines or third-party virtual machines - into &product-name;. With its unique ACPI power - status support, &product-name; can even report - to ACPI-aware guest OSes the power status of the host. For - mobile systems running on battery, the guest can thus - enable energy saving and notify the user of the remaining - power, for example in full screen modes. + supported by &product-name;. This enables easy cloning of + disk images from real machines or third-party virtual + machines into &product-name;. With its unique + ACPI power status support, + &product-name; can even report to ACPI-aware guest OSes + the power status of the host. For mobile systems running + on battery, the guest can thus enable energy saving and + notify the user of the remaining power, for example in + full screen modes. @@ -503,5 +505,5 @@ virtual channel support, &product-name; also enables you to connect arbitrary USB devices locally to a virtual - machine which is running remotely on a &product-name; RDP + machine which is running remotely on an &product-name; RDP server. See . @@ -546,5 +548,6 @@ - Windows 10 Anniversary Update (1607 / 2016 LTSB) build 14393 + Windows 10 Anniversary Update (1607 / 2016 LTSB) build + 14393 @@ -564,5 +567,6 @@ - Windows 10 October 2018 Update (1809 / 2019 LTSC) build 17763 + Windows 10 October 2018 Update (1809 / 2019 LTSC) build + 17763 @@ -668,5 +672,5 @@ - Redhat Enterprise Linux 6, 7 and 8 + Red Hat Enterprise Linux 6, 7 and 8 @@ -740,14 +744,14 @@ - - - - - Host CPU Requirements - - - SSE2 is required, starting with &product-name; version 5.2.10 and - version 5.1.24. - + + + Host CPU Requirements + + + SSE2 (Streaming SIMD Extensions 2) support is required for host + CPUs. + + + @@ -788,6 +792,6 @@ Oracle provides a single extension pack, available from: http://www.virtualbox.org. - The extension pack provides the following added functionality: + url="http://www.virtualbox.org" />. The + extension pack provides the following added functionality: @@ -829,10 +833,10 @@ - + @@ -847,7 +851,7 @@ &product-name; extension packages have a - .vbox-extpack file name - extension. To install an extension, simply double-click on the - package file and a Network Operations + .vbox-extpack file name extension. To + install an extension, simply double-click on the package file + and a Network Operations Manager window is shown to guide you through the required steps. @@ -891,7 +895,7 @@ Programs menu, click on the item in the VirtualBox group. - On Vista or Windows 7, you can also enter - VirtualBox in the search box - of the Start menu. + On some Windows platforms, you can also enter + VirtualBox in the search box of the + Start menu. @@ -912,7 +916,6 @@ either the System or System Tools group of your Applications menu. - Alternatively, you can enter - VirtualBox in a terminal - window. + Alternatively, you can enter VirtualBox in + a terminal window. @@ -1002,11 +1005,13 @@ - The Name of the VM will later - be shown in the machine list of the VirtualBox Manager window, - and it will be used for the VM's files on disk. Even though - any name can be used, bear in mind that if you create a few - VMs, you will appreciate if you have given your VMs rather - informative names."My VM" would thus be less useful than - "Windows XP SP2 with OpenOffice", for example. + The Name of the VM you choose + is shown in the machine list of the VirtualBox Manager window + and is also used for the VM's files on disk. + + + + Be sure to assign each VM an informative name that describes + the OS and software running on the VM. For example, + Windows 10 with Visio. @@ -1022,12 +1027,11 @@ - For Operating System Type - select the OS that you want to install later. The supported - OSes are grouped. If you want to install something very - unusual that is not listed, select - Other. Depending on your - selection, &product-name; will enable or disable certain VM - settings that your guest OS may require. This is particularly - important for 64-bit guests. See + For Operating System Type, + select the OS that you want to install. The supported OSes are + grouped. If you want to install something very unusual that is + not listed, select Other. + Depending on your selection, &product-name; will enable or + disable certain VM settings that your guest OS may require. + This is particularly important for 64-bit guests. See . It is therefore recommended to always set it to the correct value. @@ -1049,31 +1053,31 @@ Choose this setting carefully. The memory you give to the VM will not be available to your host OS while the VM is - running, so do not specify more than you can spare. For - example, if your host machine has 1 GB of RAM and you enter - 512 MB as the amount of RAM for a particular virtual - machine, while that VM is running, you will only have 512 MB - left for all the other software on your host. If you run two - VMs at the same time, even more memory will be allocated for - the second VM, which may not even be able to start if that - memory is not available. On the other hand, you should - specify as much as your guest OS and your applications will - require to run properly. + running, so do not specify more than you can spare. + + + + For example, if your host machine has 4 GB of RAM and you + enter 2048 MB as the amount of RAM for a particular virtual + machine, you will only have 2 GB left for all the other + software on your host while the VM is running. If you run + two VMs at the same time, even more memory will be allocated + for the second VM, which may not even be able to start if + that memory is not available. + + + + On the other hand, you should specify as much as your guest + OS and your applications will require to run properly. A + guest OS may require at least 1 or 2 GB of memory to install + and boot up. For best performance, more memory than that may + be required. - A Windows XP guest will require at least a few hundred MB of - RAM to run properly, and Windows Vista will not install with - less than 512 MB. If you want to run graphics-intensive - applications in your VM, you may require even more RAM. - - - - As a rule of thumb, if you have 1 GB of RAM or more in your - host computer, it is usually safe to allocate 512 MB to each - VM. In any case, make sure you always have at least 256 to 512 - MB of RAM left on your host OS. Otherwise you may cause your - host OS to excessively swap out memory to your hard disk, - effectively bringing your host system to a standstill. + Always ensure that the host OS has enough RAM remaining. If + insufficient RAM remains, the system might excessively swap + memory to the hard disk, which effectively brings the host + system to a standstill. @@ -1094,7 +1098,7 @@ &product-name; can provide hard disk space to a VM, see , but the most common way is to use - a large image file on your "real" hard disk, whose contents + a large image file on your physical hard disk, whose contents &product-name; presents to your VM as if it were a complete - hard disk. This file represents an entire hard disk then, so + hard disk. This file then represents an entire hard disk, so you can even copy it to another host and use it with another &product-name; installation. @@ -1107,5 +1111,5 @@
Creating a New Virtual Machine: Hard Disk - + A dynamically allocated - file will only grow in size when the guest - actually stores data on its virtual hard disk. It will - therefore initially be small on the host hard drive and - only later grow to the size specified as it is filled with - data. - - - - - - A fixed-size file will - immediately occupy the file specified, even if only a - fraction of the virtual hard disk space is actually in + file only grows in size when the guest actually + stores data on its virtual hard disk. Therefore, this file + is small initially. As the drive is filled with data, the + file grows to the specified size. + + + + + + A fixed-size file + immediately occupies the file specified, even if only a + fraction of that virtual hard disk space is actually in use. While occupying much more space, a fixed-size file incurs less overhead and is therefore slightly faster than @@ -1201,11 +1204,12 @@ - To prevent your physical hard disk from running full, - &product-name; limits the size of the image file. Still, it - needs to be large enough to hold the contents of your OS and - the applications you want to install. For a modern Windows or - Linux guest, you will probably need several gigabytes for any - serious use. The limit of the image file size can be changed - later, see . + To prevent your physical hard disk (host OS) from filling up, + &product-name; limits the size of the image file. But the + image file must be large enough to hold the contents of the + guest OS and the applications you want to install. For a + Windows or Linux guest, you will probably need several + gigabytes for any serious use. The limit of the image file + size can be changed later, see + . @@ -1275,9 +1279,9 @@ - Go to the VirtualBox VMs - folder in your system user's home directory. Find the - subdirectory of the machine you want to start and double-click - on the machine settings file. This file has a - .vbox file extension. + Go to the VirtualBox VMs folder in your + system user's home directory. Find the subdirectory of the + machine you want to start and double-click on the machine + settings file. This file has a .vbox file + extension. @@ -1386,11 +1390,11 @@ - Otherwise, if the virtual machine only sees standard PS/2 mouse - and keyboard devices, since the OS in the virtual machine does - not know that it is not running on a real computer, it expects - to have exclusive control over your keyboard and mouse. But - unless you are running the VM in full screen mode, your VM needs - to share keyboard and mouse with other applications and possibly - other VMs on your host. + Otherwise, if the virtual machine detects only standard PS/2 + mouse and keyboard devices, since the OS in the virtual machine + does not know that it is not running on a real computer, it + expects to have exclusive control over your keyboard and mouse. + But unless you are running the VM in full screen mode, your VM + needs to share keyboard and mouse with other applications and + possibly other VMs on your host. @@ -1450,15 +1454,14 @@ Note that while the VM owns the keyboard, some key - sequences, such as Alt-Tab, will no longer be seen by the + sequences, such as Alt+Tab, will no longer be seen by the host, but will go to the guest instead. After you press the Host key to reenable the host keyboard, all key presses will - go through the host again, so that sequences such as Alt-Tab + go through the host again, so that sequences such as Alt+Tab will no longer reach the guest. For technical reasons it may not be possible for the VM to get all keyboard input even when it does own the keyboard. Examples of this are the - Ctrl-Alt-Del sequence on Windows hosts or single keys - grabbed by other applications on X11 hosts like the GNOME - desktop's "Control key highlights mouse pointer" - functionality. + Ctrl+Alt+Del sequence on Windows hosts or single keys + grabbed by other applications on X11 hosts such as the GNOME + desktop Locate Pointer feature. @@ -1488,10 +1491,10 @@ - As this behavior can be inconvenient, &product-name; provides a - set of tools and device drivers for guest systems called the - &product-name; Guest Additions which make VM keyboard and mouse - operation a lot more seamless. Most importantly, the Additions - will get rid of the second "guest" mouse pointer and make your - host mouse pointer work directly in the guest. See + As this behavior is inconvenient, &product-name; provides a set + of tools and device drivers for guest systems called the + &product-name; Guest Additions. These tools make VM keyboard and + mouse operations much more seamless. Most importantly, the Guest + Additions suppress the second "guest" mouse pointer and make + your host mouse pointer work directly in the guest. See . @@ -1504,10 +1507,9 @@ - OSes expect certain key combinations to initiate certain - procedures. Some of these key combinations may be difficult to - enter into a virtual machine, as there are three candidates as - to who receives keyboard input: the host OS, &product-name;, or - the guest OS. Which of these three receives keypresses depends - on a number of factors, including the key itself. + Some OSes expect certain key combinations to initiate certain + procedures. The key combinations that you type into a VM might + target the host OS, the &product-name; software, or the guest + OS. The recipient of these keypresses depends on a number of + factors, including the key combination itself. @@ -1517,11 +1519,10 @@ Host OSes reserve certain key combinations for themselves. - For example, it is impossible to enter the + For example, you cannot use the Ctrl+Alt+Delete combination - if you want to reboot the guest OS in your virtual machine, - because this key combination is usually hard-wired into the - host OS, both Windows and Linux intercept this, and pressing - this key combination will therefore reboot your - host. + to reboot the guest OS in your VM because this key + combination is usually hard-wired into the host OS. So, even + though both the Windows and Linux OSes intercept this key + combination, only the host OS would be rebooted. @@ -1543,7 +1544,7 @@ where Fx is one of the function keys from F1 to F12, normally enables you to switch between virtual terminals. As - with Ctrl+Alt+Delete, these combinations are intercepted by - the host OS and therefore always switch terminals on the - host. + with Ctrl+Alt+Delete, these + combinations are intercepted by the host OS and therefore + always switch terminals on the host. @@ -1563,7 +1564,8 @@ virtual machine window. This menu includes the settings Insert Ctrl+Alt+Delete - and Ctrl+Alt+Backspace. - The latter will only have an effect with Linux or Oracle - Solaris guests, however. + and Insert + Ctrl+Alt+Backspace. However, the latter + setting affects only Linux guests or Oracle Solaris + guests. @@ -1576,8 +1578,7 @@ - Use special key combinations with the Host key, normally - the right Control key. &product-name; will then - translate these key combinations for the virtual - machine: + Use special key combinations with the Host key, which is + normally the right Control key. &product-name; then + translates the following key combinations for the VM: @@ -1586,6 +1587,7 @@ - Host key + Del to - send Ctrl+Alt+Del to reboot the guest. + Host key + Del + sends Ctrl+Alt+Del + to reboot the guest OS. @@ -1594,7 +1596,8 @@ Host key + - Backspace to send Ctrl+Alt+Backspace to - restart the graphical user interface of a Linux or - Oracle Solaris guest. + Backspace sends + Ctrl+Alt+Backspace + to restart the graphical user interface of a Linux + or Oracle Solaris guest. @@ -1603,7 +1606,8 @@ Host key + Function - key. For example, to simulate Ctrl+Alt+Fx - to switch between virtual terminals in a Linux - guest. + key. For example, use this key + combination to simulate + Ctrl+Alt+Fx to + switch between virtual terminals in a Linux guest. @@ -1618,5 +1622,5 @@ For some other keyboard combinations such as - Alt-Tab to switch between + Alt+Tab to switch between open windows, &product-name; enables you to configure whether these combinations will affect the host or the @@ -1626,4 +1630,11 @@ Preferences, Input. + + + + + + A soft keyboard can be used to input key combinations in the + guest. See . @@ -1675,6 +1686,6 @@ - You can resize the virtual machine's window when it is running. - In that case, one of the following things will happen: + You can resize the VM's window while that VM is running. When + you do, the window is scaled as follows: @@ -1795,7 +1806,6 @@ This will send an ACPI shutdown signal to the virtual machine, which has the same effect as if you had pressed the - power button on a real computer. So long as the VM is - running a fairly modern OS, this should trigger a proper - shutdown mechanism from within the VM. + power button on a real computer. This should trigger a + proper shutdown mechanism from within the VM. @@ -2085,5 +2095,5 @@
Snapshots List For a Virtual Machine - + The memory state file can be as large as the memory size of - the virtual machine and will therefore occupy quite some - disk space as well. + the VM and will therefore occupy considerable disk space. @@ -2557,6 +2566,34 @@ Cloud service formats. Export - to cloud services such as &oci; is supported. Import is not - supported. See . + to and import from cloud services such as &oci; is supported. + See the following topics: + + + + + + + + + + + + + + + + + + + + Before using &product-name; with &oci; there are some initial + configuration steps you need to consider. See + . + + + + &product-name; can also be used to create new instances from a + custom image stored on &oci;. See + @@ -2592,6 +2629,5 @@ &product-name; supports all appliances created by other virtualization software. For a list of known limitations, see - . + . @@ -2609,7 +2645,7 @@ . They also include a textual description file in an XML dialect with an - .ovf extension. These files - must then reside in the same directory for &product-name; to - be able to import them. + .ovf extension. These files must then + reside in the same directory for &product-name; to be able + to import them. @@ -2619,8 +2655,8 @@ Alternatively, the above files can be packed together into a single archive file, typically with an - .ova extension. Such - archive files use a variant of the TAR archive format and - can therefore be unpacked outside of &product-name; with any - utility that can unpack standard TAR files. + .ova extension. Such archive files use + a variant of the TAR archive format and can therefore be + unpacked outside of &product-name; with any utility that can + unpack standard TAR files. @@ -2666,13 +2702,12 @@ Select File, - Import - Appliance from the VirtualBox Manager window. + Import Appliance from the + VirtualBox Manager window. From the file dialog, go to the file with either the - .ovf or the - .ova file extension. + .ovf or the .ova + file extension. @@ -2742,5 +2777,5 @@ Import Hard Drives as VDI: Imports hard drives in the VDI format - rather that in the defalut VMDK format. + rather than in the default VMDK format. @@ -2828,5 +2863,6 @@ The &oci; value exports - export to &oci;. See . + the appliance to &oci;. See + . @@ -2902,15 +2938,12 @@ - - - Exporting an Appliance to &oci; - - - &product-name; supports the export of VMs to an &oci; service. - - - - Before you can export a VM to &oci;, ensure that you perform the - following configuration steps: + + + Preparing for &oci; Integration + + + There are some common configuration steps you need to take + before using &product-name; to integrate with your &oci; + account. @@ -2919,6 +2952,7 @@ - Generate an API signing key pair that is used for API - requests to &oci;. + Create a key pair. Generate + an API signing key pair that is used for API requests to + &oci;. @@ -2928,7 +2962,6 @@ The key pair is usually installed in the - .oci folder in your - home directory. For example, - ~/.oci on a Linux + .oci folder in your home directory. + For example, ~/.oci on a Linux system. @@ -2950,17 +2983,14 @@ - https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm#How - - - - - - Create a profile for your cloud account. - - - - The cloud profile contains resource identifiers for your - cloud account, such as your user OCID, and the fingerprint - for your public key. You can create a cloud profile in the + + + + + + + Create a cloud profile. The + cloud profile contains resource identifiers for your cloud + account, such as your user OCID, and the fingerprint for + your public key. You can create a cloud profile in the following ways: @@ -2970,5 +3000,5 @@ - Automatically by using the Cloud + Automatically, by using the Cloud Profile Manager. See . @@ -2978,9 +3008,16 @@ - Manually by creating an - oci_config file in your - &product-name; global configuration directory. For - example, this is - $HOME/.config/VirtualBox/oci_config + Automatically, by using the VBoxManage + cloudprofile command. See + . + + + + + + Manually, by creating an oci_config + file in your &product-name; global configuration + directory. For example, this is + $HOME/.config/VirtualBox/oci_config on a Linux host. @@ -2989,9 +3026,8 @@ - Manually by creating a - config file in your - &oci; configuration directory. For example, this is - $HOME/.oci/config on a - Linux host. + Manually, by creating a config file + in your &oci; configuration directory. For example, this + is $HOME/.oci/config on a Linux + host. @@ -3003,8 +3039,8 @@ &product-name; automatically uses the - config file if no cloud - profile file is present in your global configuration - directory. Alternatively, you can import this file - manually into the Cloud Profile Manager. + config file if no cloud profile + file is present in your global configuration directory. + Alternatively, you can import this file manually into + the Cloud Profile Manager. @@ -3018,16 +3054,49 @@ - https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htm - - - - - - Ensure that the subnets that are used by source VMs are - available in the target compartment on the cloud service. + + + + + + + Custom Linux images. To + export a custom Linux image, prepare the VM as described + here: + + + + + + + + + + Subnets. When exporting a + VM to cloud, ensure that the subnets that are used by source + VMs are available in the target compartment on the cloud + service. + + + + + + Exporting an Appliance to &oci; + + + &product-name; supports the export of VMs to an &oci; service. + The exported VM is stored on &oci; as a custom image. You can + configure whether a cloud instance is created and started after + the export process has completed. + + + + Before you can export a VM to &oci; ensure that you have done + the required preconfiguration tasks, as described in + . + @@ -3074,5 +3143,6 @@
- Appliance Settings Screen, Showing Cloud Profile Settings + Appliance Settings Screen, Showing Cloud Profile and Machine Creation + Settings @@ -3081,42 +3151,116 @@ +
+ + + In the Machine Creation + field, select an option to configure settings for a cloud + instance created when you export to &oci;. The options + enable you to do one of the following: + + + + + + + Configure settings for the cloud instance + after you have finished exporting + the VM. + + + + + + Configure settings for the cloud instance + before you start to export the VM. + + + + + + Do not create a cloud instance when you export the VM. + + + + Click Next to make an API request to the &oci; service and open the - Virtual System - Settings screen. - - - - - - Optionally edit settings used for the virtual machine on - &oci;. - - - - For example, you can edit the Disk Size and Shape used for - the VM instance. - + Virtual System Settings + screen. + + + + + + Optionally edit storage settings used for the exported + virtual machine in &oci;. You can change the following + settings: + + + + + + + The name of the bucket used to store the exported files. + + + + + + Whether to store the custom image in &oci;. + + + + + + The name for the custom image in &oci;. + + + + + + The launch mode for the custom image. + + + + Paravirtualized mode + gives improved performance and should be suitable for + most &product-name; VMs. + + + + Emulated mode is + suitable for legacy OS images. + + + + Click Export to export the - VMs to the cloud service. - - - - The VMs are uploaded to &oci;. - - - - Instances are created for the uploaded VMs. - - - - By default, the VM instance is started after upload to - &oci;. + VM to &oci;. + + + + Depending on the selection in the + Machine Creation field, the + Cloud Virtual Machine + Settings screen may be displayed before or after + export. This screen enables you to configure settings for + the cloud instance, such as Shape and Disk Size. + + + + Click Create. The VM is + exported to &oci;. + + + + Depending on the Machine + Creation setting, a cloud instance may be started + after upload to &oci; is completed. @@ -3140,123 +3284,16 @@ - Importing an instance from &oci; - - - &product-name; supports the import of cloud instance from an &oci; service. - - - - Before you can import an instance from &oci;, ensure that you perform the - following configuration steps: - - - - - - - Generate an API signing key pair that is used for API - requests to &oci;. - - - - - - - The key pair is usually installed in the - .oci folder in your - home directory. For example, - ~/.oci on a Linux - system. - - - - - - Upload the public key of the key pair to the cloud - service. - - - - - - - For step-by-step instructions for creating and uploading an - API signing key for &oci;, see: - - - - https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm#How - - - - - - Create a profile for your cloud account. - - - - The cloud profile contains resource identifiers for your - cloud account, such as your user OCID, and the fingerprint - for your public key. You can create a cloud profile in the - following ways: - - - - - - - Automatically by using the Cloud - Profile Manager. See - . - - - - - - Manually by creating an - oci_config file in your - &product-name; global configuration directory. For - example, this is - $HOME/.config/VirtualBox/oci_config - on a Linux host. - - - - - - Manually by creating a - config file in your - &oci; configuration directory. For example, this is - $HOME/.oci/config on a - Linux host. - - - - This is the same file that is used by the &oci; command - line interface. - - - - &product-name; automatically uses the - config file if no cloud - profile file is present in your global configuration - directory. Alternatively, you can import this file - manually into the Cloud Profile Manager. - - - - - - - For more information about the cloud profile settings used - by &oci; see: - - - - https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htm - - - - + Importing an Instance from &oci; + + + &product-name; supports the import of cloud instances from an + &oci; service. + + + + Before you can import an instance from &oci; ensure that you + have done the required preconfiguration tasks, as described in + . + @@ -3270,5 +3307,11 @@ Select File, Import Appliance to open - the Import Virtual Appliance wizard. + the Import Virtual + Appliance wizard. + + + + In the Source drop-down + list, select &oci;. @@ -3289,24 +3332,37 @@ - Choose the interesting cloud instance from the list Machines. - - - - Click Next - to make an API request to the &oci; service and open the Appliance Settings screen. - - - - - - Optionally edit settings used for new local virtual machine. - - - - For example, you can edit the VM name, CPUs, RAM memory, OS type, OS version. - - - - Click Import to import the instance from the cloud service. + Choose the required cloud instance from the list in the + Machines field. + + + + Click Next to make an API + request to the &oci; service and open the + Appliance Settings screen. + + + + + + Optionally edit settings for the new local virtual machine. + + + + For example, you can edit the VM name and description. + + +
+ Import Cloud Instance Screen, Showing Profile Settings and VM Settings + + + + + +
+ + + Click Import to import the + instance from the cloud service. @@ -3319,45 +3375,4 @@ - - - General OCI import logic: - - - - - A custom image created from the boot volume of the instance. - - - - - The custom image exported into OCI object and stored in the OCI Object Storage in the bucket pointed by user. - - - - - The OCI object is downloaded to the local host. OCI object is a TAR archive which contains a boot volume of instance - in QCOW2 format and JSON file with some meta-data related to the instance. - - - - - The boot volume of instance is extracted from the archive and new VMDK image is created by conversion the boot volume - into the VMDK format. The VMDK image is registered in the VirtualBox. - - - - - New VM is created with the VMDK image created on the previous step. - - - - - The downloaded OCI object (TAR archive) is deleted after successful import. - - - - - By default, the VM isn't launched after import from &oci;. - @@ -3366,4 +3381,71 @@ . + + + + Importing an Instance: Overview of Events + + + The following describes the sequence of events when you import + an instance from &oci;. + + + + + + + A custom image is created from the boot volume of the + instance. + + + + + + The custom image is exported to an &oci; object and is + stored using Object Storage in the bucket specified by the + user. + + + + + + The &oci; object is downloaded to the local host. The + object is a TAR archive which contains a boot volume of + the instance in QCOW2 format and a JSON file containing + metadata related to the instance. + + + + + + The boot volume of the instance is extracted from the + archive and a new VMDK image is created by converting the + boot volume into the VMDK format. The VMDK image is + registered with &product-name;. + + + + + + A new VM is created using the VMDK image for the cloud + instance. + + + + By default, the new VM is not started after import from + &oci;. + + + + + + The downloaded TAR archive is deleted after a successful + import. + + + + + + @@ -3397,12 +3479,12 @@ - Use the Cloud Profile Manager to create a new cloud profile - automatically. Or, create a cloud profile by importing settings - from your &oci; configuration file into the Cloud Profile - Manager. - - - - Perform the following steps to create a new cloud profile: + You can use the Cloud Profile Manager to create a new cloud + profile automatically or to create a cloud profile by importing + settings from your &oci; configuration file. + + + + Perform the following steps to create a new cloud profile + automatically: @@ -3484,6 +3566,6 @@ The cloud profile settings are saved in the - oci_config file in your - &product-name; global settings directory. + oci_config file in your &product-name; + global settings directory. @@ -3500,9 +3582,7 @@ - Ensure that a config file - is present in your &oci; configuration directory. For - example, this is - $HOME/.oci/config on a - Linux host. + Ensure that a config file is present in + your &oci; configuration directory. For example, this is + $HOME/.oci/config on a Linux host. @@ -3530,6 +3610,6 @@ Your cloud profile settings are saved to the - oci_config file in your - &product-name; global settings directory. + oci_config file in your &product-name; + global settings directory. @@ -3554,4 +3634,121 @@ + + + + + + Creating New Cloud Instances from a Custom Image + + + You can use &product-name; to create new instances from a custom + image on your cloud service. + + + + describes how to create a + custom image when you are exporting a VM to &oci;. Using a + custom image means that you can quickly create cloud instances + without having to upload your image to the cloud service every + time. + + + + Before you can create a new cloud instance in &oci; ensure that + you have done the required preconfiguration tasks, as described + in . + + + + Perform the following steps to create a new cloud instance on + &oci;: + + + + + + + Select File, + New Cloud VM to open the + Create Cloud Virtual + Machine wizard. + + + + + + From the Destination + drop-down list, select + &oci;. + + + + In the Account drop-down + list, select your &oci; account. + + + + You can set up &oci; accounts by using the Cloud Profile + Manager. + + + + The list after the Account + field shows the profile settings for your cloud account. + + + + In the Images list, select + from the custom images available on &oci;. + + +
+ New Cloud VM Wizard, Showing List of Custom Images + + + + + +
+ + + Click Next to make an API + request to the &oci; service and open the + Cloud Virtual Machine + Settings screen. + + + + + + Optionally edit settings used for the instance on &oci;. + + + + For example, you can edit the Disk Size and Shape used for + the VM instance and the networking configuration. + + + + Click Create to create the + new cloud instance. + + + + + + Monitor the instance creation process by using the &oci; + Console. + + + + + + + You can also use the VBoxManage cloud + instance command to create and manage instances on a + cloud service. See . + @@ -3582,5 +3779,5 @@ General. Enables the user to - specify the default folder/directory for VM files, and the + specify the default folder or directory for VM files, and the VRDP Authentication Library. @@ -3590,8 +3787,8 @@ Input. Enables the user to - specify the Host key. It identifies the key that toggles - whether the cursor is in the focus of the VM or the Host OS - windows, see , and which is - also used to trigger certain VM actions, see + specify the Host key. This is the key that toggles whether the + cursor is in the focus of the VM or the Host OS windows, see + . The Host key is also used + to trigger certain VM actions, see . @@ -3715,3 +3912,277 @@ + + + Soft Keyboard + + + &product-name; provides a soft keyboard that + enables you to input keyboard characters on the guest. A soft + keyboard is an on-screen keyboard that can be used as an + alternative to a physical keyboard. See + for details of how to use the + soft keyboard. + + + + + For best results, ensure that the keyboard layout configured on + the guest OS matches the keyboard layout used by the soft + keyboard. &product-name; does not do this automatically. + + + +
+ Soft Keyboard in a Guest Virtual Machine + + + + + +
+ + + The soft keyboard can be used in the following scenarios: + + + + + + + When the physical keyboard on the host is not the same as the + keyboard layout configured on the guest. For example, if the + guest is configured to use an international keyboard, but the + host keyboard is US English. + + + + + + To send special key combinations to the guest. Note that some + common key combinations are also available in the + Input, + Keyboard menu of the guest VM + window. See . + + + + + + For guests in kiosk mode, where a physical keyboard is not + present. + + + + + + When using nested virtualization, the soft keyboard provides a + method of sending key presses to a guest. + + + + + + + By default, the soft keyboard includes some common international + keyboard layouts. You can copy and modify these to meet your own + requirements. See . + + + + + Using the Soft Keyboard + + + + + + Display the soft keyboard. + + + + In the guest VM window, select + Input, + Keyboard, + Soft Keyboard. + + + + + + Select the required keyboard layout. + + + + The name of the current keyboard layout is displayed in the + task bar of the soft keyboard window. This is the previous + keyboard layout that was used. + + + + Click the Layout List icon + in the task bar of the soft keyboard window. The + Layout List window is + displayed. + + + + Select the required keyboard layout from the entries in the + Layout List window. + + + + The keyboard display graphic is updated to show the + available input keys. + + + + + + Use the soft keyboard to enter keyboard characters on the + guest. + + + + + + + Modifier keys such as Shift, Ctrl, and Alt are available + on the soft keyboard. Click once to select the modifier + key, click twice to lock the modifier key. + + + + The Reset the Keyboard and Release + All Keys icon can be used to release all + pressed modifier keys, both on the host and the guest. + + + + + + To change the look of the soft keyboard, click the + Settings icon in the + task bar. You can change colors used in the keyboard + graphic, and can hide or show sections of the keyboard, + such as the NumPad or multimedia keys. + + + + + + + + + + + + + Creating a Custom Keyboard Layout + + + You can use one of the supplied default keyboard layouts as the + starting point to create a custom keyboard layout. + + + + + To permananently save a custom keyboard layout, you must save + it to file. Otherwise, any changes you make are discarded when + you close down the Soft + Keyboard window. + + + + Custom keyboard layouts that you save are stored as an XML + file on the host, in the keyboardLayouts + folder in the global configuration data directory. For + example, in + $HOME/.config/VirtualBox/keyboardLayouts + on a Linux host. + + + + + + + + Display the Layout List. + + + + Click the Layout List icon + in the task bar of the soft keyboard window. + + + + + + Make a copy of an existing keyboard layout. + + + + Highlight the required layout and click the + Copy the Selected Layout + icon. + + + + A new layout entry with a name suffix of + -Copy is created. + + + + + + Edit the new keyboard layout. + + + + Highlight the new layout in the Layout + List and click the Edit the + Selected Layout icon. + + + + Enter a new name for the layout. + + + + Edit keys in the new layout. Click on the key that you want + to edit and enter new key captions in the + Captions fields. + + + + The keyboard graphic is updated with the new captions. + + + + + + (Optional) Save the layout to file. This means that your + custom keyboard layout will be available for future use. + + + + Highlight the new layout in the Layout + List and click the Save the + Selected Layout into File icon. + + + + Any custom layouts that you create can later be removed from + the Layout List, by highlighting and clicking the + Delete the Selected Layout + icon. + + + + + + + + + Index: /trunk/doc/manual/en_US/user_KnownIssues.xml =================================================================== --- /trunk/doc/manual/en_US/user_KnownIssues.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_KnownIssues.xml (revision 82350) @@ -37,9 +37,9 @@ - - - PCI pass-through (Linux hosts only) - - + @@ -63,5 +63,5 @@ - Host CD/DVD drive pass-through + Host CD/DVD drive passthrough @@ -108,7 +108,7 @@ 32-bit guests on AMD CPUs. This affects mainly Windows and Oracle Solaris guests, but possibly also some Linux kernel - revisions. Partially solved in 3.0.6 for 32-bit Windows - NT, 2000, XP, and 2003 guests. Requires Guest Additions - 3.0.6 or later to be installed. + revisions. Partially solved for 32-bit Windows NT, 2000, + XP, and 2003 guests. Requires the Guest Additions to be + installed. @@ -121,7 +121,6 @@ affects mainly Windows and Oracle Solaris guests, but possibly also some Linux kernel revisions. Partially - solved in 3.0.12 for 32-bit Windows NT, 2000, XP, and 2003 - guests. Requires Guest Additions 3.0.12 or later to be - installed. + solved for 32-bit Windows NT, 2000, XP, and 2003 guests. + Requires the Guest Additions to be installed. @@ -134,28 +133,6 @@ NX (no execute, data execution prevention) only works for guests running on 64-bit - hosts or guests running on 32-bit hosts with PAE enabled and - requires that hardware virtualization be enabled. - - - - - - For basic Direct3D support in Windows - guests to work, the Guest Additions must be - installed in Windows safe mode. Press F8 when the Windows - guest is booting and select Safe - Mode, then install the Guest Additions. Otherwise - the Windows file protection mechanism will interfere with the - replacement DLLs installed by &product-name; and keep - restoring the original Windows system DLLs. - - - - - This does not apply to the WDDM - Direct3D video driver available for Vista and Windows 7 - guests shipped with &product-name; 4.1. - - + hosts and requires that hardware virtualization be enabled. + @@ -173,10 +150,9 @@ guest's group policy must be changed. To do so, open the group policy editor on the command line by typing - gpedit.msc, open the key - Computer Configuration\Windows - Settings\Security Settings\Local Policies\Security - Options and change the value of - Accounts: Limit local account use of blank - passwords to console logon only to Disabled. + gpedit.msc, open the key Computer + Configuration\Windows Settings\Security Settings\Local + Policies\Security Options and change the value of + Accounts: Limit local account use of blank passwords + to console logon only to Disabled. @@ -186,5 +162,5 @@ Compacting virtual disk images is limited to VDI files. The VBoxManage - modifyhd --compact command is currently only + modifymedium --compact command is currently only implemented for VDI files. At the moment the only way to optimize the size of a virtual disk images in other formats, @@ -236,8 +212,7 @@ Neither scale mode nor - seamless mode work - correctly with guests using OpenGL 3D features, such as with - compiz-enabled window managers. + seamless mode work correctly + with guests using OpenGL 3D features, such as with + Compiz-enabled window managers. @@ -246,5 +221,5 @@ The RDP server in the &product-name; extension pack supports - only audio streams in format 22.05kHz stereo 16 bit. If the + only audio streams in format 22.05kHz stereo 16-bit. If the RDP client requests any other audio format there will be no audio. @@ -331,6 +306,6 @@ Depending on your system and version of Mac OS X, you might experience guest hangs after some time. This can be - fixed by turning off energy saving. Set timeout to "Never" - in the system preferences. + fixed by turning off energy saving. Set the timeout to + "Never" in the system preferences. @@ -346,5 +321,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal2/EfiBootArgs" " " +$ VBoxManage setextradata VM-name "VBoxInternal2/EfiBootArgs" " " @@ -353,5 +328,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal2/EfiBootArgs" "" +$ VBoxManage setextradata VM-name "VBoxInternal2/EfiBootArgs" "" @@ -359,6 +334,6 @@ It is currently not possible to start a Mac OS X guest in - safe mode by specifying "-x" option in - "VBoxInternal2/EfiBootArgs" extradata. + safe mode by specifying the option in + VBoxInternal2/EfiBootArgs extradata. @@ -373,11 +348,4 @@ - - - - There is no support for USB devices connected to Oracle - Solaris 10 hosts. - - @@ -416,9 +384,8 @@ Crossbow-based bridged networking on Oracle Solaris 11 hosts does not work directly with aggregate links. - However, you can use - dladm to manually create - a VNIC over the aggregate link and use that with a VM. - This limitation does not exist in Oracle Solaris 11u1 - build 17 and newer. + However, you can use dladm to manually + create a VNIC over the aggregate link and use that with a + VM. This limitation does not exist in Oracle Solaris 11u1 + build 17 and later. @@ -429,45 +396,10 @@ - Guest Additions of version 4.1, 4.1.2 - and 4.1.4 for Windows. The &product-name; WDDM - Video driver may be installed and remain in the guest system - when Guest additions uninstallation is performed. This is - caused by a bug in Guest Additions uninstaller. - - - - - This does not apply to a Guest - Additions update. Installing one version of Guest Additions - on top of another works correctly. - - - - - To solve this problem, uninstall the &product-name; WDDM Video - driver manually. Open Device Manager, and check whether the - Display Adapter is named "&product-name; Graphics Adapter ..". - If not, there is nothing to be done. If it is, right-click the - &product-name; Graphics Adapter in Device Manager, select - Uninstall, check - Delete the Driver Software for this - Device and click - OK. Once uninstallation is - done, start Device Manager, go to the - Action menu and select - Scan for Hardware Changes to - ensure that the correct Windows default driver be picked up - for the Graphics adapter. - - - - - - Neither virtio nor Intel - PRO/1000 drivers for Windows - XP guests support segmentation offloading. - Therefore Windows XP guests have slower transmission rates - comparing to other guest types. Refer to MS Knowledge base - article 842264 for additional information. + Neither virtio nor Intel PRO/1000 drivers for + Windows XP guests support + segmentation offloading. Therefore Windows XP guests have + slower transmission rates comparing to other guest types. + Refer to MS Knowledge base article 842264 for additional + information. Index: /trunk/doc/manual/en_US/user_Networking.xml =================================================================== --- /trunk/doc/manual/en_US/user_Networking.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Networking.xml (revision 82350) @@ -150,5 +150,5 @@ http://www.linux-kvm.org/page/WindowsGuestDrivers. + url="http://www.linux-kvm.org/page/WindowsGuestDrivers" />. @@ -189,8 +189,8 @@ present, but that there is no connection. This is as if no Ethernet cable was plugged into the card. Using this mode, it - is possible to "pull" the virtual Ethernet cable and disrupt - the connection, which can be useful to inform a guest - operating system that no network connection is available and - enforce a reconfiguration. + is possible to pull the virtual Ethernet + cable and disrupt the connection, which can be useful to + inform a guest operating system that no network connection is + available and enforce a reconfiguration. @@ -534,6 +534,6 @@ ports on the host which are not already in use by a service. For example, to set up incoming NAT connections to an - ssh server in the guest, use - the following command: + ssh server in the guest, use the following + command: @@ -543,11 +543,11 @@ In the above example, all TCP traffic arriving on port 2222 on any host interface will be forwarded to port 22 in the guest. - The protocol name tcp is a - mandatory attribute defining which protocol should be used for - forwarding, udp could also be - used. The name guestssh is - purely descriptive and will be auto-generated if omitted. The - number after denotes the network card, - as with other VBoxManage commands. + The protocol name tcp is a mandatory + attribute defining which protocol should be used for forwarding, + udp could also be used. The name + guestssh is purely descriptive and will be + auto-generated if omitted. The number after + denotes the network card, as with other + VBoxManage commands. @@ -601,9 +601,9 @@ PXE booting is now supported in NAT mode. The NAT DHCP server provides a boot file name of the form - vmname.pxe if the directory - TFTP exists in the directory - where the user's VirtualBox.xml - file is kept. It is the responsibility of the user to provide - vmname.pxe. + vmname.pxe if + the directory TFTP exists in the directory + where the user's VirtualBox.xml file is + kept. It is the responsibility of the user to provide + vmname.pxe. @@ -625,9 +625,9 @@ ICMP protocol limitations. Some frequently used network debugging tools, such as - ping or tracerouting, rely - on the ICMP protocol for sending and receiving messages. - While ICMP support has been improved with &product-name; - 2.1, meaning ping should - now work, some other tools may not work reliably. + ping or traceroute, + rely on the ICMP protocol for sending and receiving + messages. &product-name; ICMP support has some limitations, + meaning ping should work but some other + tools may not work reliably. @@ -643,5 +643,6 @@ WINS always works. As a workaround, you can use the numeric IP of the desired server in the - \\server\share notation. + \\server\share + notation. @@ -663,7 +664,7 @@ Solaris, and 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. + root. As a result, if you try to + configure such a port forwarding, the VM will refuse to + start. @@ -768,7 +769,6 @@ Port-forwarding is supported, using the - --port-forward-4 switch for IPv4 - and --port-forward-6 for IPv6. - For example: + switch for IPv4 and + for IPv6. For example: @@ -1002,6 +1002,5 @@ If you do not specify a network name, the network card will be - attached to the network - intnet by default. + attached to the network intnet by default. @@ -1032,13 +1031,12 @@ - Host-only networking is another networking mode that was added - with version 2.2 of &product-name;. It can be thought of as a - hybrid between the bridged and internal networking modes. As with - bridged networking, the virtual machines can talk to each other - and the host as if they were connected through a physical Ethernet - switch. As with internal networking, a physical networking - interface need not be present, and the virtual machines cannot - talk to the world outside the host since they are not connected to - a physical networking interface. + Host-only networking can be thought of as a hybrid between the + bridged and internal networking modes. As with bridged networking, + the virtual machines can talk to each other and the host as if + they were connected through a physical Ethernet switch. As with + internal networking, a physical networking interface need not be + present, and the virtual machines cannot talk to the world outside + the host since they are not connected to a physical networking + interface. @@ -1085,6 +1083,7 @@ - On the command line, enter VBoxManage modifyvm - "VM name" --nic<x> hostonly. See + On the command line, enter VBoxManage modifyvm + "vmname + --nicx hostonly. See . @@ -1096,6 +1095,7 @@ Before you can attach a VM to a host-only network you have to - create at least one host-only interface. You can use the GUI for - this. Choose File, + create at least one host-only interface. You can use the + VirtualBox Manager for this. Choose + File, Preferences, Network, @@ -1241,8 +1241,7 @@ On UNIX-based hosts, such as Linux, Oracle Solaris, and 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 source UDP port, the VM will refuse to - start. + applications that are not run by root. As a + result, if you try to configure such a source UDP port, the VM + will refuse to start. @@ -1353,5 +1352,5 @@ documentation accompanying the software. See also http://wiki.virtualsquare.org/wiki/index.php/VDE_Basic_Networking. + url="http://wiki.virtualsquare.org/wiki/index.php/VDE_Basic_Networking" />. @@ -1520,7 +1519,7 @@ - deny, which hides any - traffic not intended for the VM's network adaptor. This is - the default setting. + deny, which hides any traffic not + intended for the VM's network adaptor. This is the default + setting. @@ -1528,7 +1527,7 @@ - allow-vms, which hides - all host traffic from the VM's network adaptor, but allows - it to see traffic from and to other VMs. + allow-vms, which hides all host traffic + from the VM's network adaptor, but allows it to see + traffic from and to other VMs. @@ -1536,7 +1535,6 @@ - allow-all, which removes - all restrictions. The VM's network adaptor sees all - traffic. + allow-all, which removes all + restrictions. The VM's network adaptor sees all traffic. Index: /trunk/doc/manual/en_US/user_Preface.xml =================================================================== --- /trunk/doc/manual/en_US/user_Preface.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Preface.xml (revision 82350) @@ -11,5 +11,5 @@ - The &product-name; User Manual provides an + The &product-name; User Manual provides an introduction to using &product-name;. The manual provides information on how to install &product-name; and use it to create @@ -39,5 +39,5 @@ - + @@ -72,7 +72,7 @@ - monospace: Monospace type - indicates commands within a paragraph, URLs, code in examples, - text that appears on the screen, or text that you enter. + monospace: Monospace type indicates + commands within a paragraph, URLs, code in examples, text that + appears on the screen, or text that you enter. @@ -82,6 +82,9 @@ - - + + + Index: /trunk/doc/manual/en_US/user_PrivacyPolicy.xml =================================================================== --- /trunk/doc/manual/en_US/user_PrivacyPolicy.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_PrivacyPolicy.xml (revision 82350) @@ -15,5 +15,5 @@ The Oracle Privacy Policies posted on - https://www.oracle.com/legal/privacy/privacy-policy.html + apply to your personal data collected and used by Oracle. The following privacy information describes in more detail which @@ -84,5 +84,5 @@ § 6 Updates. Oracle may update the privacy policy at any time by posting a new version at - https://www.oracle.com/legal/privacy/privacy-policy.html + and the privacy information will be kept up to date in the documentation which comes with the &product-name; application. You Index: /trunk/doc/manual/en_US/user_Security.xml =================================================================== --- /trunk/doc/manual/en_US/user_Security.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Security.xml (revision 82350) @@ -97,5 +97,5 @@ The &product-name; base package should be downloaded only from a trusted source, for instance the official website - http://www.virtualbox.org. + . The integrity of the package should be verified with the provided SHA256 checksum which can be found on the official @@ -558,10 +558,10 @@ - Mitigation options: + The following mitigation options are available. - Disable nested paging + Disable Nested Paging @@ -578,5 +578,5 @@ guests may be able to cope with dropping these features after installation. Also, for some guests, especially in SMP - configurations, there could be stability issues arrising from + configurations, there could be stability issues arising from disabling nested paging. Finally, some workloads may experience a performance degradation. @@ -587,5 +587,5 @@ - Flushing the level 1 data cache + Flushing the Level 1 Data Cache @@ -627,6 +627,6 @@ A more aggressive flushing option is provided via the - VBoxManage modifyvm option - --l1d-flush-on-vm-entry. When + VBoxManage modifyvm + option. When enabled the level 1 data cache will be flushed on every VM entry. The performance impact is greater than with the default @@ -638,10 +638,6 @@ For users not concerned by this security issue, the default - mitigation can be disabled using - - - - VBoxManage modifyvm name --l1d-flush-on-sched - off + mitigation can be disabled using the VBoxManage modifyvm + name --l1d-flush-on-sched off command. @@ -656,71 +652,70 @@ These security issues affect a range of Intel CPUs starting with - Nehalem. The CVE-2018-12130 also affects some Atom Silvermont, - Atom Airmont, and Knights family CPUs, however the scope is so limited - that the host OS should deal with it for us and VBox therefore not - be affected (leaks only happens when entering and leaving C states). - - - - Mitigation option: + Nehalem. The CVE-2018-12130 also affects some Atom Silvermont, + Atom Airmont, and Knights family CPUs, however the scope is so + limited that the host OS should deal with it and &product-name; + is therefore not affected. Leaks only happens when entering and + leaving C states. + + + + The following mitigation option is available. - Buffer overwriting and disabling HT - - - First, up to date CPU microcode is a prerequisite for the buffer - overwriting (clearing) mitigations. Some host OSes may install - these automatically, though it has traditionally been a task best - performed by the system firmware. So, please check with your - system / mainboard manufacturer for the latest firmware update. - - - - This mitigation aims at removing potentially sensitive data from - the affected buffers before running guest code. Since this means - additional work each time the guest is scheduled, there might be - some performance side effects. - - - - We recommend disabling hyper threading on host affected by - CVE-2018-12126 and CVE-2018-12127 because the affected sets of - buffers are normally shared between thread pairs and therefore - cause leaks between the threads. This is traditionally done from - the firmware setup, but some OSes also offers ways disable HT. In - some cases it may be disabled by default, but please verify as the - effectiveness of the mitigation depends on it. - - - - The default action taken by VirtualBox is to clear the affected - buffers when a thread is scheduled to execute guest code, rather - than on each VM entry. This reduces the performance impact, while - making the assumption that the host OS will not handle security - sensitive data from interrupt handlers and similar without taking - precautions. - - - - A more aggressive flushing option is provided via the - VBoxManage modifyvm option - --mds-clear-on-vm-entry. When - enabled the affected buffers will be cleared on every VM entry. - The performance impact is greater than with the default option, - though this of course depends on the workload. Workloads producing - a lot of VM exits (like networking, VGA access, and similiar) will - probably be most impacted. + Buffer Overwriting and Disabling Hyper-Threading + + + First, up to date CPU microcode is a prerequisite for the + buffer overwriting (clearing) mitigations. Some host OSes may + install these automatically, though it has traditionally been + a task best performed by the system firmware. Please check + with your system or mainboard manufacturer for the latest + firmware update. + + + + This mitigation aims at removing potentially sensitive data + from the affected buffers before running guest code. Since + this means additional work each time the guest is scheduled, + there might be some performance side effects. + + + + We recommend disabling hyper-threading (HT) on hosts affected + by CVE-2018-12126 and CVE-2018-12127, because the affected + sets of buffers are normally shared between thread pairs and + therefore cause leaks between the threads. This is + traditionally done from the firmware setup, but some OSes also + offers ways disable HT. In some cases it may be disabled by + default, but please verify as the effectiveness of the + mitigation depends on it. + + + + The default action taken by &product-name; is to clear the + affected buffers when a thread is scheduled to execute guest + code, rather than on each VM entry. This reduces the + performance impact, while making the assumption that the host + OS will not handle security sensitive data from interrupt + handlers and similar without taking precautions. + + + + The VBoxManage modifyvm command provides a more + aggressive flushing option is provided by means of the + option. When + enabled the affected buffers will be cleared on every VM + entry. The performance impact is greater than with the default + option, though this of course depends on the workload. + Workloads producing a lot of VM exits (like networking, VGA + access, and similiar) will probably be most impacted. For users not concerned by this security issue, the default - mitigation can be disabled using - - - - VBoxManage modifyvm name --mds-clear-on-sched - off + mitigation can be disabled using the VBoxManage modifyvm + name --mds-clear-on-sched off command. Index: /trunk/doc/manual/en_US/user_Storage.xml =================================================================== --- /trunk/doc/manual/en_US/user_Storage.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Storage.xml (revision 82350) @@ -52,12 +52,12 @@ - Hard Disk Controllers: IDE, SATA (AHCI), SCSI, SAS, USB MSD, NVMe - - - In a real PC, hard disks and CD/DVD drives are connected to a - device called hard disk controller which drives hard disk - operation and data transfers. &product-name; can emulate the five - most common types of hard disk controllers typically found in - today's PCs: IDE, SATA (AHCI), SCSI, SAS, USB-based, and NVMe mass + Hard Disk Controllers + + + In a computing device, hard disks and CD/DVD drives are connected + to a device called hard disk controller which drives hard disk + operation and data transfers. &product-name; can emulate the most + common types of hard disk controllers typically found in computing + devices: IDE, SATA (AHCI), SCSI, SAS, USB-based, and NVMe mass storage devices. @@ -68,5 +68,5 @@ IDE (ATA) controllers are a - backwards compatible yet very advanced extension of the disk + backwards-compatible yet very advanced extension of the disk controller in the IBM PC/AT (1984). Initially, this interface worked only with hard disks, but was later extended to also @@ -116,6 +116,6 @@ - Serial ATA (SATA) is a newer - standard introduced in 2003. Compared to IDE, it supports both + Serial ATA (SATA) is a more + recent standard than IDE. Compared to IDE, it supports both much higher speeds and more devices per controller. Also, with physical hardware, devices can be added and removed while the @@ -147,9 +147,10 @@ seen by OSes that do not have device support for AHCI. In particular, there is no support for AHCI in - Windows before Windows Vista. So Windows XP, even - SP3, will not see such disks unless you install additional - drivers. It is possible to switch from IDE to SATA after - installation by installing the SATA drivers and changing the - controller type in the VM + Windows versions before Windows Vista. Legacy + Windows versions such as Windows XP, even with SP3 + installed, will not see such disks unless you install + additional drivers. It is possible to switch from IDE to + SATA after installation by installing the SATA drivers and + changing the controller type in the VM Settings dialog. @@ -158,6 +159,5 @@ &product-name; recommends the Intel Matrix Storage drivers, which can be downloaded from - http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101. + . @@ -188,10 +188,10 @@ SCSI is another established industry standard, standing for Small Computer System - Interface. SCSI was standardized as early as 1986 as a generic - interface for data transfer between all kinds of devices, - including storage devices. Today SCSI is still used for - connecting hard disks and tape devices, but it has mostly been - displaced in commodity hardware. It is still in common use in - high-performance workstations and servers. + Interface. SCSI is as a generic interface for data transfer + between all kinds of devices, including storage devices. SCSI + is still used for connecting some hard disks and tape devices, + but it has mostly been displaced in commodity hardware. It is + still in common use in high-performance workstations and + servers. @@ -199,6 +199,6 @@ Primarily for compatibility with other virtualization software, &product-name; optionally supports LSI Logic and - BusLogic SCSI controllers, to each of which up to 15 virtual - hard disks can be attached. + BusLogic SCSI controllers, to each of which up to fifteen + virtual hard disks can be attached. @@ -229,9 +229,8 @@ Serial Attached SCSI (SAS) is another bus standard which uses the SCSI command set. As - opposed to SCSI, however, with physical devices, serial cables - are used instead of parallel ones, which simplifies physical - device connections. In some ways, therefore, SAS is to SCSI - what SATA is to IDE: it enables more reliable and faster - connections. + opposed to SCSI physical devices, serial cables are used + instead of parallel cables. This simplifies physical device + connections. In some ways, therefore, SAS is to SCSI what SATA + is to IDE: it enables more reliable and faster connections. @@ -260,8 +259,8 @@ class is a standard to connect external storage devices like hard disks or flash drives to a host through USB. - All major OSes support these devices for a long time and ship - generic drivers making third-party drivers superfluous. In - particular, legacy OSes without support for SATA controllers - may benefit from USB mass storage devices. + All major OSes support these devices and ship generic drivers + making third-party drivers superfluous. In particular, legacy + OSes without support for SATA controllers may benefit from USB + mass storage devices. @@ -287,9 +286,9 @@ Non volatile memory express - (NVMe) is a standard which emerged in 2011 for - connecting non volatile memory (NVM) directly over PCI express - to lift the bandwidth limitation of the previously used SATA - protocol for SSDs. Unlike other standards the command set is - very simple to achieve maximum throughput and is not + (NVMe) is a standard for connecting non volatile + memory (NVM) directly over PCI Express to lift the bandwidth + limitation of the previously used SATA protocol for + solid-state devices. Unlike other standards the command set is + very simple in order to achieve maximum throughput and is not compatible with ATA or SCSI. OSes need to support NVMe devices to make use of them. For example, Windows 8.1 added native @@ -391,5 +390,5 @@ to a physical disk however, &product-name; enables you to expand an image file after creation, even if it has data already. See - . + . @@ -503,8 +502,6 @@ - Registered media, for compatibility with &product-name; - versions older than version 4.0. For details about how media - registration has changed with version 4.0, see - . + Registered media, for compatibility with legacy &product-name; + versions. @@ -572,24 +569,57 @@ - Add an image to the registry. - - - - - - Copy a virtual hard disk to - create another one. - - - - You can specify one of the following target types: VDI, VHD, - or VMDK. - - - - - - Move an image that is - currently in the registry to another location. + Add an image to the known + media. + + + + + + Create a new disk image. + + + + + + + For virtual hard disks, the Create + Virtual Hard Disk wizard is shown. + + + + + + For optical disks, the VISO + Creator screen is shown. This enables you to + create a virtual ISO from selected files on the host. + + + + + + For floppy disks, the Floppy Disk + Creator screen is shown. + + + + + + + + + Copy an image to create + another one. + + + + For virtual hard disks, you can specify one of the following + target types: VDI, VHD, or VMDK. + + + + + + Move an image to another + location. @@ -625,5 +655,5 @@ Remove an image from the - registry. You can optionally delete the image file when + known media. You can optionally delete the image file when removing the image. @@ -635,4 +665,11 @@ from a VM. This action only applies if the image is currently attached to a VM as a virtual hard disk. + + + + + + Search for an image by name + or UUID. @@ -729,8 +766,8 @@ - You can copy hard disk image files to other host systems and - import them in to VMs from the host system. However, certain guest - OSes, such as Windows 2000 and Windows XP, require that you - configure the new VM in a similar way to the old one. + You can copy hard disk image files to other host systems and then + import them in to VMs from the host system. However, some Windows + guest OSes may require that you configure the new VM in a similar + way to the old one. @@ -765,8 +802,8 @@ By default, images are in normal mode. To mark an existing image with one of the non-standard modes listed - below, use VBoxManage modifyhd. See - . Alternatively, use - VBoxManage to attach the image to a VM and use - the argument. See + below, use VBoxManage modifymedium. See + . Alternatively, use + VBoxManage storageattach to attach the image to + a VM and specify the argument. See . @@ -794,9 +831,10 @@ The image file itself is not reset. Instead, when a snapshot - is taken, &product-name; "freezes" the image file and no - longer writes to it. For the write operations from the VM, a - second, differencing image file is - created which receives only the changes to the original image. - See . + is taken, &product-name; freezes the + image file and no longer writes to it. For the write + operations from the VM, a second, + differencing image file is created which + receives only the changes to the original image. See + . @@ -903,6 +941,6 @@ startup does not fit your needs, you can turn it off using the parameter of VBoxManage - modifyhd. See - . + modifymedium. See + . @@ -1062,12 +1100,12 @@ Snapshots. When you create a snapshot, as explained in the previous section, &product-name; - "freezes" the images attached to the virtual machine and - creates differencing images for each image that is not in - "write-through" mode. From the point of view of the virtual - machine, the virtual disks continue to operate before, but all - write operations go into the differencing images. Each time - you create another snapshot, for each hard disk attachment, - another differencing image is created and attached, forming a - chain or tree. + freezes the images attached to the + virtual machine and creates differencing images for each image + that is not in write-through mode. From + the point of view of the virtual machine, the virtual disks + continue to operate before, but all write operations go into + the differencing images. Each time you create another + snapshot, for each hard disk attachment, another differencing + image is created and attached, forming a chain or tree. @@ -1164,8 +1202,8 @@ However, you should only make copies of virtual disk images using the utility supplied with - &product-name;. See . This - is because &product-name; assigns a UUID to each disk image, which - is also stored inside the image, and &product-name; will refuse to - work with two images that use the same number. If you do + &product-name;. See . + This is because &product-name; assigns a UUID to each disk image, + which is also stored inside the image, and &product-name; will + refuse to work with two images that use the same number. If you do accidentally try to reimport a disk image which you copied normally, you can make a second copy using the VBoxManage @@ -1174,13 +1212,13 @@ - Note that newer Linux distributions identify the boot hard disk - from the ID of the drive. The ID &product-name; reports for a - drive is determined from the UUID of the virtual disk image. So if - you clone a disk image and try to boot the copied image the guest + Note that Linux distributions identify the boot hard disk from the + ID of the drive. The ID &product-name; reports for a drive is + determined from the UUID of the virtual disk image. So if you + clone a disk image and try to boot the copied image the guest might not be able to determine its own boot disk as the UUID changed. In this case you have to adapt the disk ID in your boot loader script, for example - /boot/grub/menu.lst. The disk ID - looks like the following: + /boot/grub/menu.lst. The disk ID looks like + the following: @@ -1300,5 +1338,5 @@ - For the above reasons, &product-name; now uses SATA controllers by + For the above reasons, &product-name; uses SATA controllers by default for new virtual machines. @@ -1395,11 +1433,10 @@ Medium changes can be prevented by the guest, and &product-name; reflects that by locking the host drive if appropriate. You can - force a medium removal in such situations by using the - &product-name; GUI or the VBoxManage command - line tool. Effectively this is the equivalent of the emergency - eject which many CD/DVD drives provide, with all associated side - effects. The guest OS can issue error messages, just like on real - hardware, and guest applications may misbehave. Use this with - caution. + force a medium removal in such situations by using the VirtualBox + Manager or the VBoxManage command line tool. + Effectively this is the equivalent of the emergency eject which + many CD/DVD drives provide, with all associated side effects. The + guest OS can issue error messages, just like on real hardware, and + guest applications may misbehave. Use this with caution. @@ -1448,8 +1485,7 @@ - There is a Passthrough check box - in the GUI dialog for configuring the media attached to a storage - controller, or you can use the - option with VBoxManage storageattach. See + To enable host drive passthrough you can use the + option of the VBoxManage + storageattach command. See . @@ -1475,13 +1511,13 @@ - iSCSI stands for "Internet SCSI" and is a standard that supports - use of the SCSI protocol over Internet (TCP/IP) connections. - Especially with the advent of Gigabit Ethernet, it has become - affordable to attach iSCSI storage servers simply as remote hard - disks to a computer network. In iSCSI terminology, the server - providing storage resources is called an iSCSI - target, while the client connecting to the server and - accessing its resources is called an iSCSI - initiator. + iSCSI stands for Internet SCSI and is a + standard that supports use of the SCSI protocol over Internet + (TCP/IP) connections. Especially with the advent of Gigabit + Ethernet, it has become affordable to attach iSCSI storage servers + simply as remote hard disks to a computer network. In iSCSI + terminology, the server providing storage resources is called an + iSCSI target, while the client connecting to + the server and accessing its resources is called an + iSCSI initiator. @@ -1509,7 +1545,7 @@ vboximg-mount is a command line utility for Mac - OS X hosts that provides raw access to an &product-name; virtual - disk image on the host system. Use this utility to mount, view, - and optionally modify the disk image contents. + OS and Linux hosts that provides raw access to an &product-name; + virtual disk image on the host system. Use this utility to mount, + view, and optionally modify the disk image contents. @@ -1560,7 +1596,17 @@ + The vboximg-mount command includes experimental + read-only access to file systems inside a VM disk image. This + feature enables you to extract some files from the disk image + without starting the VM and without requiring third-party file + system drivers on the host system. FAT, NTFS, ext2, ext3, and ext4 + file systems are supported. + + + Use the option to view information about the vboximg-mount command usage. The complete - command reference is described in . + command reference is described in + . @@ -1703,6 +1749,6 @@ In this example, partition 2 is mounted on the - macos_sysdisk mount point. - The mount includes all snapshots for the disk image. + macos_sysdisk mount point. The mount + includes all snapshots for the disk image. @@ -1710,7 +1756,7 @@ - Use the host OS to mount the - vhdd device node. The - FUSE-mounted device node represents the virtual disk image. + Use the host OS to mount the vhdd device + node. The FUSE-mounted device node represents the virtual + disk image. Index: /trunk/doc/manual/en_US/user_Technical.xml =================================================================== --- /trunk/doc/manual/en_US/user_Technical.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Technical.xml (revision 82350) @@ -24,28 +24,35 @@ In &product-name;, a virtual machine and its settings are described in a virtual machine settings file in XML format. In - addition, most virtual machine have one or more virtual hard - disks, which are typically represented by disk images, such as - those in VDI format. Where all these files are stored depends on - which version of &product-name; created the machine. - - - - - Machines Created by &product-name; Version 4.0 or Later - - - By default, each virtual machine has one directory on your host + addition, most virtual machines have one or more virtual hard + disks. These are typically represented by disk images, such as + those in VDI format. The location of these files may vary, + depending on the host operating system. See + . + + + + Global configuration data for &product-name; is maintained in + another location on the host. See + . + + + + + The Machine Folder + + + By default, each virtual machine has a directory on your host computer where all the files of that machine are stored: the XML - settings file, with a .vbox - file extension, and its disk images. - - - - By default, this machine folder is placed - in a common folder called VirtualBox - VMs, which &product-name; creates in the - current system user's home directory. The location of this home - directory depends on the conventions of the host operating - system, as follows: + settings file, with a .vbox file extension, + and its disk images. This is called the machine + folder. + + + + By default, this machine folder is located in a common folder + called VirtualBox VMs, which &product-name; + creates in the current system user's home directory. The + location of this home directory depends on the conventions of + the host operating system, as follows: @@ -55,14 +62,8 @@ On Windows, this is the location returned by the - SHGetFolderPath function of - the Windows system library Shell32.dll, asking for the user - profile. On very old Windows versions which do not have this - function or where it unexpectedly returns an error, there is - a fallback based on environment variables. First, - %USERPROFILE% is checked. - If it does not exist then an attempt with - %HOMEDRIVE%%HOMEPATH% is - made. A typical location is - C:\Users\username. + SHGetFolderPath function of the Windows + system library Shell32.dll, asking for the user profile. A + typical location is + C:\Users\username. @@ -72,14 +73,17 @@ On Linux, Mac OS X, and Oracle Solaris, this is generally taken from the environment variable - $HOME, except for the user - root where it is taken from - the account database. This is a workaround for the frequent - trouble caused by users using &product-name; in combination - with the tool sudo which by - default does not reset the environment variable - $HOME. A typical location - on Linux and Oracle Solaris is - /home/username and on Mac - OS X /Users/username. + $HOME, except for the user + root where it is taken from the account + database. This is a workaround for the frequent trouble + caused by users using &product-name; in combination with the + tool sudo, which by default does not + reset the environment variable $HOME. + + + + A typical location on Linux and Oracle Solaris is + /home/username + and on Mac OS X is + /Users/username. @@ -88,8 +92,8 @@ - For simplicity, we will abbreviate the location of the home - directory as $HOME. Using that - convention, the common folder for all virtual machines is - $HOME/VirtualBox VMs. + For simplicity, we abbreviate the location of the home directory + as $HOME. Using that convention, the common + folder for all virtual machines is $HOME/VirtualBox + VMs. @@ -103,6 +107,6 @@ - A machine folder $HOME/VirtualBox - VMs/Example VM/ + A machine folder: $HOME/VirtualBox VMs/Example + VM/ @@ -110,6 +114,6 @@ - In the machine folder, a settings file: - Example VM.vbox + In the machine folder, a settings file: Example + VM.vbox @@ -118,5 +122,5 @@ In the machine folder, a virtual disk image: - Example VM.vdi. + Example VM.vdi. @@ -129,9 +133,8 @@ wizard described in . Once you start working with the VM, additional files are added. Log files - are in a subfolder called Logs, - and if you have taken snapshots, they are in a - Snapshots subfolder. For each - VM, you can change the location of its snapshots folder in the - VM settings. + are in a subfolder called Logs, and if you + have taken snapshots, they are in a + Snapshots subfolder. For each VM, you can + change the location of its snapshots folder in the VM settings. @@ -142,94 +145,18 @@ main window. Then, in the displayed window, click on the General tab. Alternatively, use - VBoxManage setproperty machinefolder. See - . + the VBoxManage setproperty machinefolder + command. See . - - - Machines Created by &product-name; Versions Before 4.0 - - - If you have upgraded to &product-name; 4.0 from an earlier - version of &product-name;, you probably have settings files and - disks in the earlier file system layout. - - - - Before version 4.0, &product-name; separated the machine - settings files from virtual disk images. The machine settings - files had an .xml file - extension and resided in a folder called - Machines under the global - &product-name; configuration directory. See - . On Linux, for example, - this was the hidden directory - $HOME/.VirtualBox/Machines. The - default hard disks folder was called - HardDisks and was also located - in the .VirtualBox folder. Both - locations could be changed by the user in the global - preferences. The concept of a default hard disk folder was - abandoned with &product-name; 4.0, since disk images now reside - in each machine's folder by default. - - - - The old layout had the following severe disadvantages: - - - - - - - It was very difficult to move a virtual machine from one - host to another because the files involved did not reside in - the same folder. In addition, the virtual media of all - machines were registered with a global registry in the - central &product-name; settings file, - $HOME/.VirtualBox/VirtualBox.xml. - - - - To move a machine to another host, it was therefore not - enough to move the XML settings file and the disk images, - which were in different locations, but the hard disk entries - from the global media registry XML had to be meticulously - copied as well. This was close to impossible if the machine - had snapshots and therefore differencing images. - - - - - - Storing virtual disk images, which can grow very large, - under the hidden - .VirtualBox directory, at - least on Linux and Oracle Solaris hosts, made many users - wonder where their disk space had gone. - - - - - - - Whereas new VMs created with &product-name; 4.0 or later will - conform to the new layout, for maximum compatibility, old VMs - are not converted to the new layout. - Otherwise machine settings would be irrevocably broken if a user - downgraded from 4.0 back to an older version of &product-name;. - - - - - Global Configuration Data - - - In addition to the files of the virtual machines, &product-name; - maintains global configuration data in the following directory: + Global Settings + + + In addition to the files for the virtual machines, + &product-name; maintains global configuration data in the + following directory: @@ -239,11 +166,5 @@ Linux and Oracle Solaris: - $HOME/.config/VirtualBox. - - - - $HOME/.VirtualBox is used - if it exists, for compatibility with legacy versions before - &product-name; 4.3. + $HOME/.config/VirtualBox. @@ -252,5 +173,5 @@ Windows: - $HOME/.VirtualBox. + $HOME/.VirtualBox. @@ -259,5 +180,5 @@ Mac OS X: - $HOME/Library/VirtualBox. + $HOME/Library/VirtualBox. @@ -267,61 +188,36 @@ &product-name; creates this configuration directory - automatically, if necessary. Optionally, you can specify an - alternate configuration directory by setting the - VBOX_USER_HOME environment - variable, or additionally on Linux or Oracle Solaris by using - the standard XDG_CONFIG_HOME - variable. Since the global - VirtualBox.xml settings file - points to all other configuration files, this enables switching - between several &product-name; configurations. - - - - Most importantly, in this directory, &product-name; stores its - global settings file, another XML file called - VirtualBox.xml. This includes - global configuration options and the list of registered virtual - machines with pointers to their XML settings files. Neither the - location of this file nor its directory has changed with - &product-name; 4.0. - - - - Before &product-name; 4.0, all virtual media, such as disk image - files, were also contained in a global registry in this settings - file. For compatibility, this media registry still exists if you - upgrade &product-name; and there are media from machines which - were created with a version before 4.0. If you have no such - machines, then there will be no global media registry. With - &product-name; 4.0, each machine XML file has its own media - registry. - - - - Also before &product-name; 4.0, the default - Machines folder and the default - HardDisks folder resided under - the &product-name; configuration directory, such as - $HOME/.VirtualBox/Machines on - Linux. If you are upgrading from an &product-name; version - before 4.0, files in these directories are not automatically - moved in order not to break backwards compatibility. + automatically, if necessary. You can specify an alternate + configuration directory by either setting the + VBOX_USER_HOME environment variable, or on + Linux or Oracle Solaris by using the standard + XDG_CONFIG_HOME variable. Since the global + VirtualBox.xml settings file points to all + other configuration files, this enables switching between + several &product-name; configurations. + + + + In this configuration directory, &product-name; stores its + global settings file, an XML file called + VirtualBox.xml. This file includes global + configuration options and a list of registered virtual machines + with pointers to their XML settings files. - - - Summary of 4.0 Configuration Changes + + + Summary of Configuration Data Locations The following table gives a brief overview of the configuration - changes between legacy versions and version 4.0 or later. - - - - Configuration Changes in Version 4.0 or Above - + data locations on an &product-name; host. + + +
+ Configuration File Locations + @@ -330,8 +226,5 @@ - Before 4.0 - - - 4.0 or above + Location @@ -343,8 +236,5 @@ - $HOME/.VirtualBox/Machines - - - $HOME/VirtualBox VMs + $HOME/VirtualBox VMs @@ -352,7 +242,4 @@ Default disk image location - - - $HOME/.VirtualBox/HardDisks @@ -365,8 +252,5 @@ - .xml - - - .vbox + .vbox @@ -376,20 +260,12 @@ - Global VirtualBox.xml - file - - Each machine settings file - - - - - Media registration - - - Explicit open/close required - - - Automatic on attach + + + + + + Media registration is done automatically when a + storage medium is attached to a VM @@ -407,5 +283,5 @@ &product-name; uses XML for both the machine settings files and the global configuration file, - VirtualBox.xml. + VirtualBox.xml. @@ -426,19 +302,4 @@ - As an example, before &product-name; 3.1, it was only possible - to enable or disable a single DVD drive in a virtual machine. If - it was enabled, then it would always be visible as the secondary - master of the IDE controller. With &product-name; 3.1, DVD - drives can be attached to arbitrary slots of arbitrary - controllers, so they could be the secondary slave of an IDE - controller or in a SATA slot. If you have a machine settings - file from an earlier version and upgrade &product-name; to 3.1 - and then move the DVD drive from its default position, this - cannot be expressed in the old settings format; the XML machine - file would get written in the new format, and a backup file of - the old format would be kept. - - - In such cases, &product-name; backs up the old settings file in the virtual machine's configuration directory. If you need to go @@ -476,12 +337,12 @@ - VBoxSVC, the &product-name; - service process which always runs in the background. This - process is started automatically by the first &product-name; - client process and exits a short time after the last client - exits. The first &product-name; service can be the GUI, - VBoxManage, - VBoxHeadless, the web service - amongst others. The service is responsible for bookkeeping, + VBoxSVC, the &product-name; service process + which always runs in the background. This process is started + automatically by the first &product-name; client process and + exits a short time after the last client exits. The first + &product-name; service can be the GUI, + VBoxManage, + VBoxHeadless, the web service amongst + others. The service is responsible for bookkeeping, maintaining the state of all VMs, and for providing communication between &product-name; components. This @@ -492,11 +353,10 @@ When we refer to clients here, we mean - the local clients of a particular - VBoxSVC server process, not - clients in a network. &product-name; employs its own - client/server design to allow its processes to cooperate, - but all these processes run under the same user account on - the host operating system, and this is totally transparent - to the user. + the local clients of a particular VBoxSVC + server process, not clients in a network. &product-name; + employs its own client/server design to allow its processes + to cooperate, but all these processes run under the same + user account on the host operating system, and this is + totally transparent to the user. @@ -505,12 +365,10 @@ - The GUI process, - VirtualBoxVM, a client + The GUI process, VirtualBoxVM, a client application based on the cross-platform Qt library. When - started without the --startvm - option, this application acts as the VirtualBox Manager, - displaying the VMs and their settings. It then communicates - settings and state changes to - VBoxSVC and also reflects + started without the option, this + application acts as the VirtualBox Manager, displaying the VMs + and their settings. It then communicates settings and state + changes to VBoxSVC and also reflects changes effected through other means, such as the VBoxManage command. @@ -520,7 +378,6 @@ - If the VirtualBoxVM client - application is started with the - --startvm argument, it loads + If the VirtualBoxVM client application is + started with the argument, it loads the VMM library which includes the actual hypervisor and then runs a virtual machine and provides the input and output for @@ -549,33 +406,32 @@ - VirtualBoxVM: The Qt front - end implementing the VirtualBox Manager and running VMs. - - - - - - VBoxManage: A less - user-friendly but more powerful alternative. See - . - - - - - - VBoxHeadless: A VM front end - which does not directly provide any video output and keyboard - or mouse input, but enables redirection through the VirtualBox - Remote Desktop Extension. See . - - - - - - vboxwebsrv: The - &product-name; web service process which enables control of an - &product-name; host remotely. This is described in detail in - the &product-name; Software Development Kit (SDK) reference. - See . + VirtualBoxVM: The Qt front end implementing + the VirtualBox Manager and running VMs. + + + + + + VBoxManage: A less user-friendly but more + powerful alternative. See . + + + + + + VBoxHeadless: A VM front end which does not + directly provide any video output and keyboard or mouse input, + but enables redirection through the VirtualBox Remote Desktop + Extension. See . + + + + + + vboxwebsrv: The &product-name; web service + process which enables control of an &product-name; host + remotely. This is described in detail in the &product-name; + Software Development Kit (SDK) reference. See + . @@ -584,6 +440,6 @@ The &product-name; Python shell: A Python alternative to - VBoxManage. This is also - described in the SDK reference. + VBoxManage. This is also described in the + SDK reference. @@ -617,11 +473,4 @@ EM (Execution Manager): Controls execution of guest code. - - - - - - REM (Recompiled Execution Monitor): Provides software - emulation of CPU instructions. @@ -662,11 +511,4 @@ PGM (Page Manager): A component that controls guest paging. - - - - - - PATM (Patch Manager): Patches guest code to improve and speed - up software virtualization. @@ -747,5 +589,5 @@ - Hardware vs. Software Virtualization + Hardware Virtualization @@ -757,10 +599,10 @@ &product-name; steps in and takes action. In particular, for lots of hardware that the guest believes to be accessing, - &product-name; simulates a certain "virtual" environment according - to how you have configured a virtual machine. For example, when - the guest attempts to access a hard disk, &product-name; redirects - these requests to whatever you have configured to be the virtual - machine's virtual hard disk. This is normally an image file on - your host. + &product-name; simulates a certain virtual + environment according to how you have configured a virtual + machine. For example, when the guest attempts to access a hard + disk, &product-name; redirects these requests to whatever you have + configured to be the virtual machine's virtual hard disk. This is + normally an image file on your host. @@ -769,5 +611,33 @@ virtualized. Detecting situations in which &product-name; needs to take control over the guest code that is executing, as described - above, is difficult. There are two ways in which to achieve this: + above, is difficult. To achieve this, &product-name; uses + hardware virtualization. + + + + Intel and AMD processors have support for hardware virtualization. + This means that these processors can help &product-name; to + intercept potentially dangerous operations that a guest operating + system may be attempting and also makes it easier to present + virtual hardware to a virtual machine. + + + + These hardware features differ between Intel and AMD processors. + Intel named its technology VT-x, AMD calls theirs AMD-V. The Intel + and AMD support for virtualization is very different in detail, + but not very different in principle. + + + + + On many systems, the hardware virtualization features first need + to be enabled in the BIOS before &product-name; can use them. + + + + + Enabling hardware virtualization is required + in the following scenarios: @@ -776,57 +646,7 @@ - Since 2006, Intel and AMD processors have had support for - so-called hardware virtualization. This - means that these processors can help &product-name; to - intercept potentially dangerous operations that a guest - operating system may be attempting and also makes it easier to - present virtual hardware to a virtual machine. - - - - These hardware features differ between Intel and AMD - processors. Intel named its technology VT-x. AMD calls theirs - AMD-V. The Intel and AMD support for virtualization is very - different in detail, but not very different in principle. - - - - - On many systems, the hardware virtualization features first - need to be enabled in the BIOS before &product-name; can use - them. - - - - - - - As opposed to other virtualization software, for many usage - scenarios, &product-name; does not - require hardware virtualization features - to be present. Through sophisticated techniques, - &product-name; virtualizes many guest operating systems - entirely in software. This means that you - can run virtual machines even on older processors which do not - support hardware virtualization. - - - - - - - Even though &product-name; does not always require hardware - virtualization, enabling it is required in - the following scenarios: - - - - - - Certain rare guest operating systems like OS/2 make use of - very esoteric processor instructions that are not supported - with our software virtualization. For virtual machines that - are configured to contain such an operating system, hardware + very esoteric processor instructions. For virtual machines + that are configured to use such an operating system, hardware virtualization is enabled automatically. @@ -835,11 +655,10 @@ - &product-name;'s 64-bit guest support, added with version 2.0, - and multiprocessing (SMP), added with version 3.0, both - require hardware virtualization to be enabled. This is not - much of a limitation since the vast majority of today's 64-bit - and multicore CPUs ship with hardware virtualization anyway. - The exceptions to this rule are older Intel Celeron and AMD - Opteron CPUs, for example. + &product-name;'s 64-bit guest and multiprocessing (SMP) + support both require hardware virtualization to be enabled. + This is not much of a limitation since the vast majority of + 64-bit and multicore CPUs ship with hardware virtualization. + The exceptions to this rule are some legacy Intel and AMD + CPUs. @@ -858,319 +677,11 @@ host, and especially if several products attempt to use hardware virtualization features such as VT-x, this can crash the entire - host. Also, within &product-name;, you can mix software and - hardware virtualization when running multiple VMs. In certain - cases a small performance penalty will be unavoidable when - mixing VT-x and software virtualization VMs. We recommend not - mixing virtualization modes if maximum performance and low - overhead are essential. This does not apply - to AMD-V. + host. - - - - - Paravirtualization Providers - - - &product-name; enables the exposure of a paravirtualization - interface, to facilitate accurate and efficient execution of - software within a virtual machine. These interfaces require the - guest operating system to recognize their presence and make use of - them in order to leverage the benefits of communicating with the - &product-name; hypervisor. - - - - Most modern, mainstream guest operating systems, including Windows - and Linux, ship with support for one or more paravirtualization - interfaces. Hence, there is typically no need to install - additional software in the guest to take advantage of this - feature. - - - - Exposing a paravirtualization provider to the guest operating - system does not rely on the choice of host platforms. For example, - the Hyper-V paravirtualization provider can - be used for VMs to run on any host platform supported by - &product-name; and not just Windows. - - - - &product-name; provides the following interfaces: - - - - - - - Minimal: Announces the - presence of a virtualized environment. Additionally, reports - the TSC and APIC frequency to the guest operating system. This - provider is mandatory for running any Mac OS X guests. - - - - - - KVM: Presents a Linux KVM - hypervisor interface which is recognized by Linux kernels - version 2.6.25 or later. &product-name;'s implementation - currently supports paravirtualized clocks and SMP spinlocks. - This provider is recommended for Linux guests. - - - - - - Hyper-V: Presents a Microsoft - Hyper-V hypervisor interface which is recognized by Windows 7 - and newer operating systems. &product-name;'s implementation - currently supports paravirtualized clocks, APIC frequency - reporting, guest debugging, guest crash reporting and relaxed - timer checks. This provider is recommended for Windows guests. - - - - - - - - - - Details About Software Virtualization - - - Implementing virtualization on x86 CPUs with no hardware - virtualization support is an extraordinarily complex task because - the CPU architecture was not designed to be virtualized. The - problems can usually be solved, but at the cost of reduced - performance. Thus, there is a constant clash between - virtualization performance and accuracy. - - - - The x86 instruction set was originally designed in the 1970s and - underwent significant changes with the addition of protected mode - in the 1980s with the 286 CPU architecture and then again with the - Intel 386 and its 32-bit architecture. Whereas the 386 did have - limited virtualization support for real mode operation with V86 - mode, as used by the "DOS Box" of Windows 3.x and OS/2 2.x, no - support was provided for virtualizing the entire architecture. - - - - In theory, software virtualization is not overly complex. There - are four privilege levels, called rings, - provided by the hardware. Typically only two rings are used: ring - 0 for kernel mode and ring 3 for user mode. Additionally, one - needs to differentiate between host context - and guest context. - - - - In host context, everything is as if no hypervisor was active. - This might be the active mode if another application on your host - has been scheduled CPU time. In that case, there is a host ring 3 - mode and a host ring 0 mode. The hypervisor is not involved. - - - - In guest context, however, a virtual machine is active. So long as - the guest code is running in ring 3, this is not much of a problem - since a hypervisor can set up the page tables properly and run - that code natively on the processor. The problems mostly lie in - how to intercept what the guest's kernel does. - - - - There are several possible solutions to these problems. One - approach is full software emulation, usually involving - recompilation. That is, all code to be run by the guest is - analyzed, transformed into a form which will not allow the guest - to either modify or see the true state of the CPU, and only then - executed. This process is obviously highly complex and costly in - terms of performance. &product-name; contains a recompiler based - on QEMU which can be used for pure software emulation, but the - recompiler is only activated in special situations, described - below. - - - - Another possible solution is paravirtualization, in which only - specially modified guest OSes are allowed to run. This way, most - of the hardware access is abstracted and any functions which would - normally access the hardware or privileged CPU state are passed on - to the hypervisor instead. Paravirtualization can achieve good - functionality and performance on standard x86 CPUs, but it can - only work if the guest OS can actually be modified, which is - obviously not always the case. - - - - &product-name; chooses a different approach. When starting a - virtual machine, through its ring-0 support kernel driver, - &product-name; has set up the host system so that it can run most - of the guest code natively, but it has inserted itself at the - "bottom" of the picture. It can then assume control when needed. - If a privileged instruction is executed, the guest traps, in - particular because an I/O register was accessed and a device needs - to be virtualized, or external interrupts occur. &product-name; - may then handle this and either route a request to a virtual - device or possibly delegate handling such things to the guest or - host OS. In guest context, &product-name; can therefore be in one - of three states: - - - - - - - Guest ring 3 code is run unmodified, at full speed, as much as - possible. The number of faults will generally be low, unless - the guest allows port I/O from ring 3. This is something we - cannot do as we do not want the guest to be able to access - real ports. This is also referred to as raw - mode, as the guest ring-3 code runs unmodified. - - - - - - For guest code in ring 0, &product-name; employs a clever - trick. It actually reconfigures the guest so that its ring-0 - code is run in ring 1 instead, which is normally not used in - x86 operating systems). As a result, when guest ring-0 code, - actually running n ring 1, such as a guest device driver - attempts to write to an I/O register or execute a privileged - instruction, the &product-name; hypervisor in the "real" ring - 0 can take over. - - - - - - The hypervisor (VMM) can be active. Every time a fault occurs, - &product-name; looks at the offending instruction and can - relegate it to a virtual device or the host OS or the guest OS - or run it in the recompiler. - - - - In particular, the recompiler is used when guest code disables - interrupts and &product-name; cannot figure out when they will - be switched back on. In these situations, &product-name; - actually analyzes the guest code using its own disassembler. - Also, certain privileged instructions such as LIDT need to be - handled specially. Finally, any real-mode or protected-mode - code, such as BIOS code, a DOS guest, or any operating system - startup, is run in the recompiler entirely. - - - - - - - Unfortunately this only works to a degree. Among others, the - following situations require special handling: - - - - - - - Running ring 0 code in ring 1 causes a lot of additional - instruction faults, as ring 1 is not allowed to execute any - privileged instructions, of which guest's ring-0 contains - plenty. With each of these faults, the VMM must step in and - emulate the code to achieve the desired behavior. While this - works, emulating thousands of these faults is very expensive - and severely hurts the performance of the virtualized guest. - - - - - - There are certain flaws in the implementation of ring 1 in the - x86 architecture that were never fixed. Certain instructions - that should trap in ring 1 do not. This - affects, for example, the LGDT/SGDT, LIDT/SIDT, or POPF/PUSHF - instruction pairs. Whereas the "load" operation is privileged - and can therefore be trapped, the "store" instruction always - succeed. If the guest is allowed to execute these, it will see - the true state of the CPU, not the virtualized state. The - CPUID instruction also has the same problem. - - - - - - A hypervisor typically needs to reserve some portion of the - guest's address space, both linear address space and - selectors, for its own use. This is not entirely transparent - to the guest OS and may cause clashes. - - - - - - The SYSENTER instruction, used for system calls, executed by - an application running in a guest OS always transitions to - ring 0. But that is where the hypervisor runs, not the guest - OS. In this case, the hypervisor must trap and emulate the - instruction even when it is not desirable. - - - - - - The CPU segment registers contain a "hidden" descriptor cache - which is not software-accessible. The hypervisor cannot read, - save, or restore this state, but the guest OS may use it. - - - - - - Some resources must, and can, be trapped by the hypervisor, - but the access is so frequent that this creates a significant - performance overhead. An example is the TPR (Task Priority) - register in 32-bit mode. Accesses to this register must be - trapped by the hypervisor. But certain guest operating - systems, notably Windows and Oracle Solaris, write this - register very often, which adversely affects virtualization - performance. - - - - - - - To fix these performance and security issues, &product-name; - contains a Code Scanning and Analysis Manager (CSAM), which - disassembles guest code, and the Patch Manager (PATM), which can - replace it at runtime. - - - - Before executing ring 0 code, CSAM scans it recursively to - discover problematic instructions. PATM then performs - in-situ patching. It replaces the instruction - with a jump to hypervisor memory where an integrated code - generator has placed a more suitable implementation. In reality, - this is a very complex task as there are lots of odd situations to - be discovered and handled correctly. So, with its current - complexity, one could argue that PATM is an advanced - in-situ recompiler. - - - - In addition, every time a fault occurs, &product-name; analyzes - the offending code to determine if it is possible to patch it in - order to prevent it from causing more faults in the future. This - approach works well in practice and dramatically improves software - virtualization performance. + + See for a technical discussion of + hardware virtualization. @@ -1270,8 +781,77 @@ software virtualization, the overhead of VM exits is relatively high. This causes problems for devices whose emulation requires - high number of traps. One example is the VGA device in 16-color - modes, where not only every I/O port access but also every access + high number of traps. One example is a VGA device in 16-color + mode, where not only every I/O port access but also every access to the framebuffer memory must be trapped. + + + + + + Paravirtualization Providers + + + &product-name; enables the exposure of a paravirtualization + interface, to facilitate accurate and efficient execution of + software within a virtual machine. These interfaces require the + guest operating system to recognize their presence and make use of + them in order to leverage the benefits of communicating with the + &product-name; hypervisor. + + + + Most modern, mainstream guest operating systems, including Windows + and Linux, ship with support for one or more paravirtualization + interfaces. Hence, there is typically no need to install + additional software in the guest to take advantage of this + feature. + + + + Exposing a paravirtualization provider to the guest operating + system does not rely on the choice of host platforms. For example, + the Hyper-V paravirtualization provider can + be used for VMs to run on any host platform supported by + &product-name; and not just Windows. + + + + &product-name; provides the following interfaces: + + + + + + + Minimal: Announces the + presence of a virtualized environment. Additionally, reports + the TSC and APIC frequency to the guest operating system. This + provider is mandatory for running any Mac OS X guests. + + + + + + KVM: Presents a Linux KVM + hypervisor interface which is recognized by Linux kernels + version 2.6.25 or later. &product-name;'s implementation + currently supports paravirtualized clocks and SMP spinlocks. + This provider is recommended for Linux guests. + + + + + + Hyper-V: Presents a Microsoft + Hyper-V hypervisor interface which is recognized by Windows 7 + and newer operating systems. &product-name;'s implementation + currently supports paravirtualized clocks, APIC frequency + reporting, guest debugging, guest crash reporting and relaxed + timer checks. This provider is recommended for Windows guests. + + + + @@ -1328,7 +908,6 @@ and overhead. This can yield a performance improvement of up to 5%. To enable this feature for a VM, you use the - VBoxManage modifyvm - --largepages command. See - . + VBoxManage modifyvm --largepages command. + See . @@ -1350,6 +929,6 @@ To enable these features for a VM, you use the - VBoxManage modifyvm --vtxvpid - and --largepages commands. + VBoxManage modifyvm --vtxvpid and + VBoxManage modifyvm --largepages commands. See . Index: /trunk/doc/manual/en_US/user_ThirdParty.xml =================================================================== --- /trunk/doc/manual/en_US/user_ThirdParty.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_ThirdParty.xml (revision 82350) @@ -24,6 +24,5 @@ of the &product-name; code which is released as open source are available at - http://www.virtualbox.org, + , both as tarballs for particular releases and as a live SVN repository. @@ -182,6 +181,5 @@ work does not require the other work to be released under the same license (see - http://etherboot.sourceforge.net/clinks.html). + ). Etherboot is @@ -3291,6 +3289,5 @@ except in compliance with the License. You may obtain a copy of the License at - http://www.cs.fsu.edu/~engelen/soaplicense.html. + . Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or Index: /trunk/doc/manual/en_US/user_Troubleshooting.xml =================================================================== --- /trunk/doc/manual/en_US/user_Troubleshooting.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_Troubleshooting.xml (revision 82350) @@ -66,16 +66,7 @@ Because of significant differences between VT-x and AMD-V, problems may be specific to one or the other technology. The - exact CPU model may also make a difference, even for - software virtualization, because different CPUs support - different features, which may affect certain aspects of - guest CPU operation. - - - - - - Is the problem specific to a certain virtualization mode? - Some problems may only occur in software virtualization - mode, others may be specific to hardware virtualization. + exact CPU model may also make a difference because different + CPUs support different features, which may affect certain + aspects of guest CPU operation. @@ -139,18 +130,18 @@ release log file is created, containing lots of information about the VM configuration and runtime - events. The log file is called - VBox.log and resides in the VM - log file folder. Typically this will be a directory as follows: - - -$HOME/VirtualBox VMs/{machinename}/Logs + events. The log file is called VBox.log and + resides in the VM log file folder, which is + $HOME/VirtualBox + VMs/VM-name/Logs by + default. + When starting a VM, the configuration file of the last run will - be renamed to .1, up to - .3. Sometimes when there is a - problem, it is useful to have a look at the logs. Also when - requesting support for &product-name;, supplying the - corresponding log file is mandatory. + be renamed to .1, up to + .3. Sometimes when there is a problem, it + is useful to have a look at the logs. Also when requesting + support for &product-name;, supplying the corresponding log file + is mandatory. @@ -164,7 +155,7 @@ - The release log file, VBox.log, contains a wealth of diagnostic - information, such as Host OS type and version, &product-name; - version and build (32-bit or 64-bit). It also includes a + The release log file, VBox.log, contains a + wealth of diagnostic information, such as Host OS type and + version, &product-name; version and build. It also includes a complete dump of the guest's configuration (CFGM), detailed information about the host CPU type and supported features, @@ -180,11 +171,10 @@ crash dumps. This is true for both host and guest crashes. For information about enabling core dumps on - Linux, Oracle Solaris, and OS X systems, refer to the following - core dump article on the &product-name; website: - - - - http://www.virtualbox.org/wiki/Core_dump. + Linux, Oracle Solaris, and Mac OS X systems, refer to the + following core dump article on the &product-name; website: + + + + . @@ -211,12 +201,100 @@ - http://www.virtualbox.org/wiki/Network_tips. + . The trace files created by &product-name; are in - .pcap format and can be easily - analyzed with Wireshark. + .pcap format and can be easily analyzed + with Wireshark. + + + + + + + Using the VBoxBugReport Command to Collect Debug Information + Automatically + + + The VBoxBugReport command is used to collect + debug information automatically for an &product-name; + installation. This command can be useful when you need to gather + information to send to Oracle Support. + + + + The following examples show how to use + VBoxBugReport. + + + + By default, the command collects VBoxSVC + process logs, device settings, and global configuration data for + an &product-name; host. + + +$ VBoxBugReport + ... + 0% - collecting VBoxSVC.log.10... + 7% - collecting VBoxSVC.log.9... + ... + 64% - collecting VBoxSVC.log.1... + 71% - collecting VBoxSVC.log... + 78% - collecting VirtualBox.xml... + 85% - collecting HostUsbDevices... + 92% - collecting HostUsbFilters... +100% - compressing... + +Report was written to '2019-03-26-13-32-02-bugreport.tgz' + + + The results are saved as a compressed tar file archive in the + same directory where the command is run. + + + + To specify a different output file location: + + +$ VBoxBugReport --output ~/debug/bug004.tgz + + + To output all debug information to a single text file, rather + than a tgz file: + + +$ VBoxBugReport --text + + + To collect information for a specific VM, called + Windows_10: + + +$ VBoxBugReport Windows_10 + + + This command collects machine settings, guest properties, and + log files for the specified VM. Global configuration information + for the host is also included. + + + + To collect information for several VMs, called + Windows_7, Windows_8, and + Windows_10: + + +$ VBoxBugReport Windows_7 Windows_8 Windows_10 + + + To collect information for all VMs: + + +$ VBoxBugReport --all + + + To show a full list of the available command options, run + VBoxBugReport --help. @@ -262,6 +340,5 @@ - Using the telnet protocol - on port 5000 + Using the telnet protocol on port 5000 @@ -277,21 +354,18 @@ - Start the VM directly using VirtualBox + Start the VM directly using VirtualBoxVM --startvm, with an additional - --dbg, - --debug, or - --debug-command-line - argument. See the VirtualBox command - usage help for details. - - - - - - Set the - VBOX_GUI_DBG_ENABLED or - VBOX_GUI_DBG_AUTO_SHOW - environment variable to - true before launching the + , , or + argument. See the + VirtualBoxVM --help command usage help + for details. + + + + + + Set the VBOX_GUI_DBG_ENABLED or + VBOX_GUI_DBG_AUTO_SHOW environment + variable to true before launching the &product-name; process. Setting these variables, only their presence is checked, is effective even when the first @@ -304,8 +378,7 @@ - Set the GUI/Dbg/Enabled - extra data item to true - before launching the VM. This can be set globally or on a - per VM basis. + Set the GUI/Dbg/Enabled extra data item + to true before launching the VM. This can + be set globally or on a per VM basis. @@ -341,103 +414,106 @@ - stop: Stops the VM - execution and enables single stepping - - - - - - g: Continue VM execution - - - - - - t: Single step an - instruction - - - - - - rg/rh/r: Print the - guest/hypervisor/current registers - - - - - - kg/kh/k: Print the - guest/hypervisor/current call stack - - - - - - da/db/dw/dd/dq: Print - memory contents as ASCII/bytes/words/dwords/qwords - - - - - - u: Unassemble memory - - - - - - dg: Print the guest's GDT - - - - - - di: Print the guest's IDT - - - - - - dl: Print the guest's LDT - - - - - - dt: Print the guest's TSS - - - - - - dp*: Print the guest's page - table structures - - - - - - bp/br: Set a - normal/recompiler breakpoint - - - - - - bl: List breakpoints - - - - - - bc: Clear a breakpoint - - - - - - writecore: Write a VM core - file to disk. See + stop: Stops the VM execution and enables + single stepping + + + + + + g: Continue VM execution + + + + + + t: Single step an instruction + + + + + + rg, rh, and + r: Print the guest, hypervisor, and + current registers + + + + + + kg, kh, and + k: Print the guest, hypervisor, and + current call stack + + + + + + da, db, + dw, dd, + dq: Print memory contents as ASCII, + bytes, words, dwords, and qwords + + + + + + u: Unassemble memory + + + + + + dg: Print the guest's GDT + + + + + + di: Print the guest's IDT + + + + + + dl: Print the guest's LDT + + + + + + dt: Print the guest's TSS + + + + + + dp*: Print the guest's page table + structures + + + + + + bp and br: Set a + normal and recompiler breakpoint + + + + + + bl: List breakpoints + + + + + + bc: Clear a breakpoint + + + + + + writecore: Write a VM core file to disk. + See @@ -446,6 +522,6 @@ - See the built-in help for other - available commands. + See the built-in help for other available + commands. @@ -459,13 +535,12 @@ the guest OS version, but there are no symbols in the guest's memory. Kernel symbols are available in the file - /proc/kallsyms on Linux guests. - This file must be copied to the host, for example using + /proc/kallsyms on Linux guests. This file + must be copied to the host, for example using scp. The loadmap debugger command can be used to make the symbol information available to - the VM debugger. Note that the - kallsyms file contains the - symbols for the currently loaded modules. If the guest's - configuration changes, the symbols will change as well and must - be updated. + the VM debugger. Note that the kallsyms + file contains the symbols for the currently loaded modules. If + the guest's configuration changes, the symbols will change as + well and must be updated. @@ -494,75 +569,69 @@ - cfgm: Print a branch of the - configuration tree - - - - - - cpuid: Display the guest - CPUID leaves - - - - - - ioport: Print registered - I/O port ranges - - - - - - mmio: Print registered MMIO - ranges - - - - - - mode -- print the current - paging mode - - - - - - pit: Print the i8254 PIT - state - - - - - - pic: Print the i8259A PIC - state - - - - - - ohci/ehci/xhci: Print a - subset of the OHCI/EHCI/xHCI USB controller state - - - - - - pcnet0: Print the PCnet - state - - - - - - vgatext: Print the contents - of the VGA framebuffer formatted as standard text mode - - - - - - timers: Print all VM timers + cfgm: Print a branch of the configuration + tree + + + + + + cpuid: Display the guest CPUID leaves + + + + + + ioport: Print registered I/O port ranges + + + + + + mmio: Print registered MMIO ranges + + + + + + mode: Print the current paging mode + + + + + + pit: Print the i8254 PIT state + + + + + + pic: Print the i8259A PIC state + + + + + + ohci, ehci, + xhci: Print a subset of the OHCI, EHCI, + and xHCI USB controller state + + + + + + pcnet0: Print the PCnet state + + + + + + vgatext: Print the contents of the VGA + framebuffer formatted as standard text mode + + + + + + timers: Print all VM timers @@ -593,6 +662,5 @@ - http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf. + . @@ -628,14 +696,13 @@ The relevant data structures and definitions can be found in the &product-name; sources under the following header files: - include/VBox/dbgfcorefmt.h, - include/iprt/x86.h and - src/VBox/Runtime/include/internal/ldrELFCommon.h. + include/VBox/dbgfcorefmt.h, + include/iprt/x86.h and + src/VBox/Runtime/include/internal/ldrELFCommon.h. The VM core file can be inspected using - elfdump and GNU - readelf or other similar - utilities. + elfdump and GNU readelf or + other similar utilities. @@ -684,6 +751,6 @@ -VBoxManage setextradata "VM name" -"VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/FlushInterval" [b] +VBoxManage setextradata VM-name +"VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/FlushInterval" [b] @@ -691,37 +758,44 @@ -VBoxManage setextradata "VM name" -"VBoxInternal/Devices/ahci/0/LUN#[x]/Config/FlushInterval" [b] - - - The value [x] that selects the disk for IDE is 0 for the master - device on the first channel, 1 for the slave device on the first - channel, 2 for the master device on the second channel or 3 for - the slave device on the second channel. For SATA use values - between 0 and 29. Only disks support this configuration option; - it must not be set for CD/DVD drives. - - - - The unit of the interval [b] is the number of bytes written - since the last flush. The value for it must be selected so that - the occasional long write delays do not occur. Since the proper - flush interval depends on the performance of the host and the - host filesystem, finding the optimal value that makes the - problem disappear requires some experimentation. Values between - 1000000 and 10000000 (1 to 10 megabytes) are a good starting - point. Decreasing the interval both decreases the probability of - the problem and the write performance of the guest. Setting the - value unnecessarily low will cost performance without providing - any benefits. An interval of 1 will cause a flush for each write - operation and should solve the problem in any case, but has a - severe write performance penalty. - - - - Providing a value of 0 for [b] is treated as an infinite flush - interval, effectively disabling this workaround. Removing the - extra data key by specifying no value for [b] has the same - effect. +VBoxManage setextradata VM-name +"VBoxInternal/Devices/ahci/0/LUN#[x]/Config/FlushInterval" [b] + + + [x] specifies the + disk for IDE. 0 represents the master device + on the first channel, 1 represents the slave + device on the first channel, 2 represents the + master device on the second channel, and 3 + represents the slave device on the second channel. For SATA, use + values between 0 and 29. + This configuration option applies to disks only. Do not use this + option for CD or DVD drives. + + + + The unit of the interval + ([b]) is the + number of bytes written since the last flush. The value for it + must be selected so that the occasional long write delays do not + occur. Since the proper flush interval depends on the + performance of the host and the host filesystem, finding the + optimal value that makes the problem disappear requires some + experimentation. Values between 1000000 and 10000000 (1 to 10 + megabytes) are a good starting point. Decreasing the interval + both decreases the probability of the problem and the write + performance of the guest. Setting the value unnecessarily low + will cost performance without providing any benefits. An + interval of 1 will cause a flush for each write operation and + should solve the problem in any case, but has a severe write + performance penalty. + + + + Providing a value of 0 for + [b] is treated as + an infinite flush interval, effectively disabling this + workaround. Removing the extra data key by specifying no value + for [b] has the + same effect. @@ -744,11 +818,12 @@ -VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/IgnoreFlush" 0 - - - The value [x] that selects the disk is 0 for the master device - on the first channel, 1 for the slave device on the first - channel, 2 for the master device on the second channel or 3 for - the master device on the second channel. +$ VBoxManage setextradata VM-name "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/IgnoreFlush" 0 + + + [x] specifies the + disk. is 0 for the master device on the first channel, 1 for the + slave device on the first channel, 2 for the master device on + the second channel or 3 for the master device on the second + channel. @@ -757,5 +832,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0 +$ VBoxManage setextradata VM-name "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0 @@ -767,8 +842,7 @@ Note that this does not affect the flushes performed according to the configuration described in - . - Restoring the default of ignoring flush commands is possible by - setting the value to 1 or by removing the key. + . Restoring the + default of ignoring flush commands is possible by setting the + value to 1 or by removing the key. @@ -780,5 +854,5 @@ - Many newer multi-core processors support some form of frequency + Many multicore processors support some form of frequency boosting, which means that if only one core is utilized, it can run possibly 50% faster or even more than the rated CPU @@ -807,5 +881,5 @@ scaling may cause CPU usage reporting to be highly misleading. This happens in situations when the host CPU load is significant - but not heavy, such as 15-30% of the maximum. + but not heavy, such as between 15% to 30% of the maximum. @@ -814,9 +888,9 @@ spent, measuring for example how many nanoseconds the systems or a process was active within one second. However, in order to - save energy, modern systems can significantly scale down CPU - speed when the system is not fully loaded. Naturally, when the - CPU is running at for example one half of its maximum speed, the - same number of instructions will take roughly twice as long to - execute compared to running at full speed. + save energy, systems can significantly scale down CPU speed when + the system is not fully loaded. When the CPU is running at for + example one half of its maximum speed, the same number of + instructions will take roughly twice as long to execute compared + to running at full speed. @@ -872,9 +946,9 @@ support in the system's BIOS should be disabled, if such a setting is available. Not all systems support the C1E power - state. On Intel systems, the Intel C - State setting should be disabled. Disabling - other power management settings may also improve performance. - However, a balance between performance and power consumption - must always be considered. + state. On Intel systems, the Intel C State + setting should be disabled. Disabling other power management + settings may also improve performance. However, a balance + between performance and power consumption must always be + considered. @@ -897,5 +971,5 @@ -VBoxTestOGL --log "log_file_name" --test 2D +$ VBoxTestOGL --log "log_file_name" --test 2D @@ -979,9 +1053,8 @@ Changing the storage controller hardware will cause bootup failures as well. This might also apply to you if you copy a - disk image from an older version of &product-name; to a - virtual machine created with a newer &product-name; version. - The default subtype of IDE controller hardware was changed - from PIIX3 to PIIX4 with &product-name; 2.2. Make sure these - settings are identical. + disk image from an older version of &product-name; to a new + virtual machine. The default subtype of IDE controller + hardware used by &product-name; is PIIX4. Make sure that the + storage controller settings are identical. @@ -1005,7 +1078,5 @@ According to Microsoft, this is due to a race condition in - Windows. A hotfix is available. See - http://support.microsoft.com/kb/955076. + Windows. A hotfix is available from Microsoft. @@ -1043,5 +1114,5 @@ Installation complains about a failure installing - msgina.dll. + msgina.dll. @@ -1066,5 +1137,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1 +$ VBoxManage setextradata VM-name "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1 @@ -1083,6 +1154,6 @@ - When Windows guests run into a kernel crash, they display the - infamous bluescreen. Depending on how Windows is configured, the + When Windows guests run into a kernel crash, they display a + bluescreen error. Depending on how Windows is configured, the information will remain on the screen until the machine is restarted or it will reboot automatically. During installation, @@ -1098,28 +1169,5 @@ -VBoxManage setextradata "VM name" "VBoxInternal/PDM/HaltOnReset" 1 - - - - - - PCnet Driver Failure in 32-bit Windows Server 2003 Guests - - - Certain editions of Windows 2000 and 2003 servers support more - than 4 GB RAM on 32-bit systems. The AMD PCnet network driver - shipped with Windows Server 2003 fails to load if the 32-bit - guest OS uses paging extensions, which will occur with more than - approximately 3.5 GB RAM assigned to the VM. - - - - This problem is known to occur with version 4.38.0.0 of the - PCnet driver. The issue was fixed in version 4.51.0.0 of the - driver, which is available as a separate download. An - alternative solution may be changing the emulated NIC type to - Intel PRO/1000 MT Desktop (82540EM), or reducing the RAM - assigned to the VM to approximately 3.5 GB or less. - +$ VBoxManage setextradata VM-name "VBoxInternal/PDM/HaltOnReset" 1 @@ -1131,6 +1179,6 @@ With Windows Vista, Microsoft dropped support for the AMD PCNet - card that &product-name; used to provide as the default virtual - network card before version 1.6.0. For Windows Vista guests, + card that legacy versions of &product-name; used to provide as + the default virtual network card. For Windows Vista guests, &product-name; now uses an Intel E1000 card by default. @@ -1152,5 +1200,5 @@ Several background applications of Windows guests, especially - virus scanners, are known to increases the CPU load notably even + virus scanners, are known to increase the CPU load notably even if the guest appears to be idle. We recommend to deactivate virus scanners within virtualized guests if possible. @@ -1168,6 +1216,6 @@ the &product-name; shared folders name service. To fix these delays, add the following entries to the file - \windows\system32\drivers\etc\lmhosts - of the Windows guest: + \windows\system32\drivers\etc\lmhosts of + the Windows guest: @@ -1194,11 +1242,10 @@ The USB HID (Human Interface Device) drivers in Windows 98 are - very old and do not handle tablets the same way as more recent - operating systems do. For example, Windows 2000 and later, Mac - OS X, and Oracle Solaris. To work around the problem, use the + very old and do not handle tablets in the same way as modern + operating systems do. To work around the problem, use the following command: -VBoxManage setextradata "VM name" "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0 +$ VBoxManage setextradata VM-name "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0 @@ -1216,223 +1263,16 @@ If a Windows guest is a member of an Active Directory domain and - the snapshot feature of &product-name; is used, it could happen - it loses this status after you restore an older snapshot. - - - - The reason is the automatic machine password changing performed + the snapshot feature of &product-name; is used, it could be + removed from the Active Direcory domain after you restore an + older snapshot. + + + + This is caused by automatic machine password changes performed by Windows at regular intervals for security purposes. You can - disable this feature by following the instruction of the - following article from Microsoft: - http://support.microsoft.com/kb/154501 - - - - - - - Restoring d3d8.dll and d3d9.dll - - - &product-name; Guest Additions for Windows prior to 4.1.8 did - not properly back up the original d3d8.dll and d3d9.dll system - files when selecting and installing the experimental Direct3D - support. This process replaces both system files with files from - the Guest Additions so that Direct3D calls can be handled - correctly. Although this issue was fixed with &product-name; - 4.1.8, there is no way the Windows Guest Additions installer can - repair these files. - - - - Corruption of these files has no implications if 3D acceleration - is enabled and basic Direct3D support is installed. That is, - without WDDM on Windows Vista or later, or on older Windows - systems like Windows XP. With the basic Direct3D support all - Direct3D 8.0 and Direct3D 9.0 applications will utilize - &product-name; Direct3D files directly and thus will run as - expected. - - - - For WDDM Direct3D support however, the originally shipped - d3d8.dll and d3d9.dll files are required in order to run - Direct3D 8.0 and Direct3D 9.0 applications. As a result of the - above mentioned system files corruption these applications will - not work anymore. See below for a step-by-step guide for - restoring the original d3d8.dll and d3d9.dll system files in - case the &product-name; Guest Additions installer warned about - those incorrect files or when having trouble running Direct3D - applications. - - - - - Starting at Windows 7 the 3D desktop, called Aero, uses - DirectX 10 for rendering so that corrupted d3d8.dll and - d3d9.dll system files will have no effect on the actual - rendering. - - - - - This is why such a detected file corruption is not considered as - fatal for the basic Direct3D installation on all supported - Windows guests, and for WDDM Direct3D installation on Windows 7 - and later guests. - - - - Extracting d3d8 and d3d9.dll from a - Windows XP installation CD: - - - - - - - Download and install the latest version of 7-Zip File - Manager. - - - - - - Browse into the installation CD. For example E:\i386, or - E:\amd64 for the 64-bit version. - - - - - - Locate the entries d3d8.dl_ and d3d9.dl_. Double-click on - the file names and extract d3d8.dll and d3d9.dll. - - - - - - Reboot Windows in Safe mode. - - - - - - Copy the extracted d3d8.dll and d3d9.dll files to - C:\Windows\system32 and C:\Windows\system32\dllcache. - - - - - - Reboot Windows. - - - - - - - Extracting d3d8 and d3d9.dll from a - Windows XP Service pack: - - - - - - - Download and install the latest version of 7-Zip File - Manager. - - - - - - Choose Open Inside, to open WindowsXP-KB936929-SP3-x86.exe - as an archive and browse the i386 directory. - - - - - - Locate the entries d3d8.dl_ and d3d9.dl_. Double-click on - the file names and extract d3d8.dll and d3d9.dll. - - - - - - Reboot Windows in Safe mode. - - - - - - Copy the extracted d3d8.dll and d3d9.dll files to - C:\Windows\system32 and C:\Windows\system32\dllcache. - - - - - - Reboot Windows. - - - - - - - Extracting d3d8 and d3d9.dll from a - Vista/Windows7 installation CD or Service Pack ISO: - - - - - - - Download and install the latest version of 7-Zip File - Manager. - - - - - - Browse into the installation CD. For example E:\sources. - - - - - - Locate file install.wim and double-click the file. After the - 7-Zip utility unzips the file, you will see a few numbered - folders. Each numeric subfolder represents a different - version of Windows such as Starter or Home Basic. - - - - - - Open one of the numeric folders and browse to the - Windows\System32 directory, or C:\Windows\SysWOW64 for the - 64-bit version. Locate and extract the d3d8.dll and d3d9.dll - files. - - - - - - Copy extracted the d3d8.dll and d3d9.dll files to - C:\Windows\system32 or C:\Windows\SysWOW64. Files from - system32 should go to system32, from SysWOW64 to SysWOW64. - - - - - - Reboot Windows. - - - - + disable this feature as shown in the following article from + Microsoft: + . + @@ -1452,7 +1292,6 @@ - This is a HIMEM.SYS limitation documented by Microsoft in - Knowledge base article KB 116256. Windows 3.1 memory limits are - described in detail in Microsoft Knowledge base article KB + This is a known HIMEM.SYS limitation. Windows 3.1 memory limits + are described in detail in Microsoft Knowledge base article KB 84388. @@ -1487,26 +1326,11 @@ - Linux kernels shipped with Red Hat Enterprise Linux (RHEL) as of - release 4.7 and 5.1 as well as kernels of related Linux - distributions, such as CentOS and Oracle Linux, support a kernel - parameter divider=N. Hence, such kernels - support a lower timer frequency without recompilation. We - suggest you add the kernel parameter - divider=10 to select a guest kernel timer - frequency of 100Hz. - - - - - - - AMD Barcelona CPUs - - - Most Linux-based guests will fail with AMD Phenoms or - Barcelona-level Opterons due to a bug in the Linux kernel. - Enable the I/O-APIC to work around the problem. See - . + Linux kernels shipped with Red Hat Enterprise Linux, as well as + kernels of related Linux distributions, such as CentOS and + Oracle Linux, support a kernel parameter + divider=N. Hence, such kernels support a + lower timer frequency without recompilation. We suggest you add + the kernel parameter divider=10 to select a + guest kernel timer frequency of 100Hz. @@ -1545,13 +1369,11 @@ If you see this message, either disable hardware virtualization or the I/O APIC as described in - , or upgrade - the guest to a newer kernel. + , or upgrade the guest to + a newer kernel. See - http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html + for details about the kernel fix. @@ -1569,14 +1391,14 @@ Guest desktop services in guests running the X11 window system such as Oracle Solaris and Linux, are provided by a guest - service called VBoxClient, - which runs under the ID of the user who started the desktop - session and is automatically started using the following command - lines when your X11 user session is started if you are using a - common desktop environment such as Gnome or KDE. - - -VBoxClient --clipboard -VBoxClient --display -VBoxClient --seamless + service called VBoxClient, which runs under + the ID of the user who started the desktop session and is + automatically started using the following command lines when + your X11 user session is started if you are using a common + desktop environment such as Gnome or KDE. + + +$ VBoxClient --clipboard +$ VBoxClient --display +$ VBoxClient --seamless @@ -1587,13 +1409,13 @@ - The VBoxClient processes create - files in the user's home directory with names of the form - .vboxclient-*.pid when they are - running in order to prevent a given service from being started - twice. It can happen due to misconfiguration that these files - are created owned by root and not deleted when the services are - stopped, which will prevent them from being started in future - sessions. If the services cannot be started, you may wish to - check whether these files still exist. + The VBoxClient processes create files in the + user's home directory with names of the form + .vboxclient-*.pid when they are running in + order to prevent a given service from being started twice. It + can happen due to misconfiguration that these files are created + owned by root and not deleted when the services are stopped, + which will prevent them from being started in future sessions. + If the services cannot be started, you may wish to check whether + these files still exist. @@ -1606,25 +1428,4 @@ Oracle Solaris Guests - - - Older Oracle Solaris 10 Releases Crash in 64-bit Mode - - - Oracle Solaris 10 releases up to and including Oracle Solaris 10 - 8/07 incorrectly detect newer Intel processors produced since - 2007. This problem leads to the 64-bit Oracle Solaris kernel - crashing, and usually causing a triple fault, almost immediately - during startup, in both virtualized and physical environments. - - - - The recommended solution is upgrading to at least Oracle Solaris - 10 5/08. Alternative solutions include forcing Oracle Solaris to - always boot the 32-bit kernel or applying a patch for bug - 6574102 while Oracle Solaris is using the 32-bit kernel. - - - - @@ -1632,14 +1433,13 @@ - When using more than one CPU, Oracle Solaris 10 5/08, Oracle - Solaris 10 10/08, and Oracle Solaris 10 5/09 may take a long - time to boot and may print warnings on the system console - regarding failures to read from disk. This is a bug in Oracle - Solaris 10 which affects specific physical and virtual - configurations. It is caused by trying to read microcode updates - from the boot disk when the disk interrupt is reassigned to a - not yet fully initialized secondary CPU. Disk reads will time - out and fail, triggering delays of about 45 seconds and - warnings. + When using more than one CPU, Oracle Solaris 10 10/08, and + Oracle Solaris 10 5/09 may take a long time to boot and may + print warnings on the system console regarding failures to read + from disk. This is a bug in Oracle Solaris 10 which affects + specific physical and virtual configurations. It is caused by + trying to read microcode updates from the boot disk when the + disk interrupt is reassigned to a not yet fully initialized + secondary CPU. Disk reads will time out and fail, triggering + delays of about 45 seconds and warnings. @@ -1649,51 +1449,4 @@ solutions include restricting the number of virtual CPUs to one or possibly using a different storage controller. - - - - - - - Solaris 8 5/01 and Earlier May Crash on Startup - - - Solaris 2.6, 7 and 8 releases up to and including Solaris 8 4/01 - ("S8U4") incorrectly set up Machine Check Exception (MCE) MSRs - on Pentium 4 and some later Intel CPUs. The problem leads to the - Solaris kernel crashing, and usually causing a triple fault, - almost immediately during startup, in both virtualized and - physical environments. Solaris 9 and later releases are not - affected by this problem, and neither is Solaris 2.5.1 and - earlier. - - - - The recommended solution is upgrading to at least Solaris 8 7/01 - ("S8U5"). Alternative solutions include applying a patch for - bugs 4408508 and 4414557 on an unaffected system. - - - - - - - - - FreeBSD Guests - - - - FreeBSD 10.0 May Hang with xHCI - - - If xHCI (USB 3.0) emulation is enabled for FreeBSD 10.0 guests, - the guest OS will hang. This is caused by the guest OS - incorrectly handling systems where Message Signaled Interrupts - (MSIs) are not used with the xHCI device. - - - - The problem does not exist in earlier FreeBSD releases and was - fixed in FreeBSD 10.1. @@ -1717,7 +1470,7 @@ interface options based on a common architecture. All global status information and configuration is maintained by the - process VBoxSVC.exe, which is - an out-of-process COM server. Whenever an &product-name; process - is started, it requests access to the COM server and Windows + process VBoxSVC.exe, which is an + out-of-process COM server. Whenever an &product-name; process is + started, it requests access to the COM server and Windows automatically starts the process. Note that it should never be started by the end user. @@ -1727,5 +1480,5 @@ When the last process disconnects from the COM server, it will terminate itself after some seconds. The &product-name; - configuration (XML files) is maintained and owned by the COM + configuration XML files are maintained and owned by the COM server and the files are locked whenever the server runs. @@ -1739,5 +1492,5 @@ subsequently other processes fail to initialize it. In these situations, it is recommended to use the Windows task manager to - kill the process VBoxSVC.exe. + kill the process VBoxSVC.exe. @@ -1746,9 +1499,9 @@ - CD/DVD Changes Not Recognized - - - In case you have assigned a physical CD/DVD drive to a guest and - the guest does not notice when the medium changes, make sure + CD and DVD Changes Not Recognized + + + In case you have assigned a physical CD or DVD drive to a guest + and the guest does not notice when the medium changes, make sure that the Windows media change notification (MCN) feature is not turned off. This is represented by the following key in the @@ -1819,9 +1572,9 @@ - Setting the environment variable - VBOX_DISABLE_HOST_DISK_CACHE to - 1 will enable a workaround for this problem until Microsoft - addresses the issue. For example, open a command prompt window - and start &product-name; like this: + Setting the VBOX_DISABLE_HOST_DISK_CACHE + environment variable to 1 enables a + workaround for this problem until Microsoft addresses the issue. + For example, open a command prompt window and start + &product-name; like this: @@ -1855,6 +1608,6 @@ The maximum allowed filter count was reached on the host. In this case, the MSI log would mention the - 0x8004a029 error code - returned on NetFlt network component install, as follows: + 0x8004a029 error code returned on NetFlt + network component install, as follows: @@ -1876,16 +1629,12 @@ - The INF cache is corrupt. In this case, the install log - (%windir%\inf\setupapi.log - on XP or - %windir%\inf\setupapi.dev.log - on Vista or later) would typically mention the failure to - find a suitable driver package for either the - sun_VBoxNetFlt or - sun_VBoxNetFltmp - components. The solution then is to uninstall - &product-name;, remove the INF cache - (%windir%\inf\INFCACHE.1), - reboot and try to reinstall &product-name;. + The INF cache is corrupt. In this case, the install log at + %windir%\inf\setupapi.dev.log would + typically mention the failure to find a suitable driver + package for either the sun_VBoxNetFlt or + sun_VBoxNetFltmp components. The solution + then is to uninstall &product-name;, remove the INF cache + (%windir%\inf\INFCACHE.1), reboot and + try to reinstall &product-name;. @@ -1903,16 +1652,12 @@ VirtualBox Manager or the VBoxManage command, then the INF cache is probably corrupt. In this case, the - install log - (%windir%\inf\setupapi.log on - Windows XP or - %windir%\inf\setupapi.dev.log - on Windows Vista or later) would typically mention the failure - to find a suitable driver package for the - sun_VBoxNetAdp component. - Again, as with the bridged networking problem described above, - the solution is to uninstall &product-name;, remove the INF - cache - (%windir%\inf\INFCACHE.1), - reboot and try to reinstall &product-name;. + install log at + %windir%\inf\setupapi.dev.log would + typically mention the failure to find a suitable driver package + for the sun_VBoxNetAdp component. Again, as + with the bridged networking problem described above, the + solution is to uninstall &product-name;, remove the INF cache + (%windir%\inf\INFCACHE.1), reboot and try + to reinstall &product-name;. @@ -1930,12 +1675,12 @@ - If the &product-name; kernel module, - vboxdrv, refuses to load you - may see an "Error inserting vboxdrv: Invalid argument" message. - As root, check the output of the dmesg - command to find out why the load failed. Most probably the - kernel disagrees with the version of gcc used - to compile the module. Make sure that you use the same compiler - as used to build the kernel. + If the &product-name; kernel module, vboxdrv, + refuses to load you may see an Error inserting vboxdrv: + Invalid argument message. As root, check the output of + the dmesg command to find out why the load + failed. Most probably the kernel disagrees with the version of + gcc used to compile the module. Make sure + that you use the same compiler that was used to build the + kernel. @@ -1944,93 +1689,22 @@ - Linux Host CD/DVD Drive Not Found - - - If you have configured a virtual machine to use the host's - CD/DVD drive, but this does not appear to work, make sure that - the current user has permission to access the corresponding - Linux device file. This is - /dev/hdc, - /dev/scd0, - /dev/cdrom or similar. On most - distributions, the user must be added to a corresponding group, - usually called cdrom or - cdrw. - - - - - - - Linux Host CD/DVD Drive Not Found (Older Distributions) - - - On older Linux distributions, if your CD/DVD device has a - different name, &product-name; may be unable to find it. On - older Linux hosts, &product-name; performs the following steps - to locate your CD/DVD drives: - - - - - - - &product-name; checks if the environment variable - VBOX_CDROM is defined. If - so, &product-name; omits all the following checks. - - - - - - &product-name; tests if - /dev/cdrom works. - - - - - - &product-name; checks if any CD/DVD drives are currently - mounted by checking - /etc/mtab. - - - - - - &product-name; checks if any of the entries in - /etc/fstab point to CD/DVD - devices. - - - - - - - You can set the VBOX_CDROM environment variable to contain a - list of your CD/DVD devices, separated by colons. For example: - - -export VBOX_CDROM='/dev/cdrom0:/dev/cdrom1' - - - On modern Linux distributions, &product-name; uses the hardware - abstraction layer (HAL) to locate CD and DVD hardware. - - - - - - - Linux Host Floppy Not Found - - - appplies - also to floppy disks, except that on older distributions - &product-name; tests for - /dev/fd* devices by default. - This can be overridden with the - VBOX_FLOPPY environment - variable. + Linux Host CD/DVD or Floppy Disk Drive Not Found + + + If you have configured a virtual machine to use the host's CD or + DVD drive or floppy disk drive, but this does not appear to + work, make sure that the current user has permission to access + the corresponding Linux device file. For example, for a CD or + DVD drive this may be /dev/hdc, + /dev/scd0, /dev/cdrom + or similar. On most distributions, the user must be added to a + corresponding group, usually called cdrom or + cdrw or floppy. + + + + On supported Linux distributions, &product-name; uses + udev to locate hardware such as CD/DVD drives + and floppy disk drives. @@ -2039,16 +1713,16 @@ - Strange Guest IDE Error Messages When Writing to CD/DVD - - - If the experimental CD/DVD writer support is enabled with an - incorrect &product-name;, host or guest configuration, it is - possible that any attempt to access the CD/DVD writer fails and - simply results in guest kernel error messages for Linux guests - or application error messages for Windows guests. &product-name; - performs the usual consistency checks when a VM is powered up. - In particular, it aborts with an error message if the device for - the CD/DVD writer is not writable by the user starting the VM. - But &product-name; cannot detect all misconfigurations. The + Strange Guest IDE Error Messages When Writing to CD or DVD + + + If the experimental CD or DVD writer support is enabled with an + incorrect host or guest configuration, it is possible that any + attempt to access the CD or DVD writer fails and simply results + in guest kernel error messages for Linux guests or application + error messages for Windows guests. &product-name; performs the + usual consistency checks when a VM is powered up. In particular, + it aborts with an error message if the device for the CD or DVD + writer is not writable by the user starting the VM. But + &product-name; cannot detect all misconfigurations. The necessary host and guest OS configuration is not specific for &product-name;, but a few frequent problems are listed here @@ -2058,28 +1732,26 @@ Special care must be taken to use the correct device. The - configured host CD/DVD device file name, in most cases - /dev/cdrom, must point to the - device that allows writing to the CD/DVD unit. For CD/DVD writer - units connected to a SCSI controller or to a IDE controller that + configured host CD or DVD device file name, in most cases + /dev/cdrom, must point to the device that + allows writing to the CD or DVD unit. For CD or DVD writer units + connected to a SCSI controller or to a IDE controller that interfaces to the Linux SCSI subsystem, common for some SATA controllers, this must refer to the SCSI device node, such as - /dev/scd0. Even for IDE CD/DVD - writer units this must refer to the appropriate SCSI CD-ROM - device node, such as /dev/scd0, - if the ide-scsi kernel module - is loaded. This module is required for CD/DVD writer support - with all Linux 2.4 kernels and some early 2.6 kernels. Many - Linux distributions load this module whenever a CD/DVD writer is - detected in the system, even if the kernel would support CD/DVD - writers without the module. &product-name; supports the use of - IDE device files, such as - /dev/hdc, provided the kernel - supports this and the ide-scsi - module is not loaded. - - - - Similar rules, except that within the guest the CD/DVD writer is - always an IDE device, apply to the guest configuration. Since + /dev/scd0. Even for IDE CD or DVD writer + units this must refer to the appropriate SCSI CD-ROM device + node, such as /dev/scd0, if the + ide-scsi kernel module is loaded. This module + is required for CD or DVD writer support with some early 2.6 + kernels. Many Linux distributions load this module whenever a CD + or DVD writer is detected in the system, even if the kernel + would support CD or DVD writers without the module. + &product-name; supports the use of IDE device files, such as + /dev/hdc, provided the kernel supports this + and the ide-scsi module is not loaded. + + + + Similar rules, except that within the guest the CD or DVD writer + is always an IDE device, apply to the guest configuration. Since this setup is very common, it is likely that the default configuration of the guest works as expected. @@ -2096,25 +1768,23 @@ Mozilla XPCOM (cross platform component object model) for interprocess and intraprocess communication (IPC). The process - VBoxSVC serves as a - communication hub between different &product-name; processes and - maintains the global configuration, such as the XML database. - When starting an &product-name; component, the processes - VBoxSVC and - VBoxXPCOMIPCD are started - automatically. They are only accessible from the user account - they are running under. VBoxSVC + VBoxSVC serves as a communication hub between + different &product-name; processes and maintains the global + configuration, such as the XML database. When starting an + &product-name; component, the processes + VBoxSVC and VBoxXPCOMIPCD + are started automatically. They are only accessible from the + user account they are running under. VBoxSVC owns the &product-name; configuration database which normally - resides in - ~/.config/VirtualBox, or the + resides in ~/.config/VirtualBox, or the appropriate configuration directory for your operating system. While it is running, the configuration files are locked. Communication between the various &product-name; components and - VBoxSVC is performed through a - local domain socket residing in - /tmp/.vbox-<username>-ipc. + VBoxSVC is performed through a local domain + socket residing in + /tmp/.vbox-username-ipc. In case there are communication problems, such as an &product-name; application cannot communicate with - VBoxSVC, terminate the daemons - and remove the local domain socket directory. + VBoxSVC, terminate the daemons and remove the + local domain socket directory. @@ -2127,9 +1797,8 @@ If USB is not working on your Linux host, make sure that the - current user is a member of the - vboxusers group. Please keep in - mind that group membership does not take effect immediately but - rather at the next login. If available, the - newgrp command may avoid the need for a + current user is a member of the vboxusers + group. Please keep in mind that group membership does not take + effect immediately but rather at the next login. If available, + the newgrp command may avoid the need for a logout and login. @@ -2143,9 +1812,8 @@ Linux kernels including the grsec patch, see - http://www.grsecurity.net/, - and derivates have to disable PAX_MPROTECT for the VBox binaries - to be able to start a VM. The reason is that VBox has to create - executable code on anonymous memory. + , and derivates have + to disable PAX_MPROTECT for the VBox binaries + to be able to start a VM. The reason is that &product-name; has + to create executable code on anonymous memory. @@ -2161,12 +1829,11 @@ fail to start with a kernel error saying that the vmalloc pool is exhausted and should be extended. The error message also - tells you to specify - vmalloc=256MB in your kernel - parameter list. If adding this parameter to your GRUB or LILO - configuration makes the kernel fail to boot, with an error - message such as "failed to mount the root partition", then you - have probably run into a memory conflict of your kernel and - initial RAM disk. This can be solved by adding the following - parameter to your GRUB configuration: + tells you to specify vmalloc=256MB in your + kernel parameter list. If adding this parameter to your GRUB or + LILO configuration makes the kernel fail to boot, with an error + message such as failed to mount the root + partition, then you have probably run into a memory + conflict of your kernel and initial RAM disk. This can be solved + by adding the following parameter to your GRUB configuration: @@ -2190,7 +1857,8 @@ lead to a heavy fragmentation of the host memory preventing &product-name; VMs from being started. We recommend to limit the - ZFS cache by adding the following line to /etc/system, where - xxxx bytes is the amount of - memory usable for the ZFS cache. + ZFS cache by adding the following line to + /etc/system, where + xxxx bytes is the amount of memory + usable for the ZFS cache. @@ -2199,68 +1867,4 @@ - - - VM Aborts With Out of Memory Errors on Oracle Solaris 10 Hosts - - - 32-bit Oracle Solaris 10 hosts (bug 1225025) require swap space - equal to, or greater than the host's physical memory size. For - example, 8 GB physical memory would require at least 8 GB swap. - This can be configured during an Oracle Solaris 10 install by - choosing a Custom Install and changing the default partitions. - - - - - This restriction applies only to 32-bit Oracle Solaris hosts, - 64-bit hosts are not affected. - - - - - For existing Oracle Solaris 10 installs, an additional swap - image needs to be mounted and used as swap. Hence if you have 1 - GB swap and 8 GB of physical memory, you require to add 7 GB - more swap. This can be done as follows: - - - - For ZFS, run the following as root user: - - -zfs create -V 8gb /_<ZFS volume>_/swap -swap -a /dev/zvol/dsk/_<ZFS volume>_/swap - - - To mount if after reboot, add the following line to /etc/vfstab: - - -/dev/zvol/dsk/_<ZFS volume>_/swap - - swap - no - - - - Alternatively, you could grow the existing swap using: - - -zfs set volsize=8G rpool/swap - - - And reboot the system for the changes to take effect. - - - - For UFS (as root user): - - -mkfile 7g /path/to/swapfile.img -swap -a /path/to/swapfile.img - - - To mount it after reboot, add the following line to /etc/vfstab: - - -/path/to/swap.img - - swap - no - - - - Index: /trunk/doc/manual/en_US/user_VBoxManage.xml =================================================================== --- /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 82350) @@ -254,27 +254,26 @@ - -v|--version: Show the - version of this tool and exit. - - - - - - --nologo: Suppress the output - of the logo information. This option is useful for scripts. - - - - - - --settingspw: Specifiy a - settings password. - - - - - - --settingspwfile: Specify a - file containing the settings password. + : Show the version of this tool + and exit. + + + + + + : Suppress the output of the logo + information. This option is useful for scripts. + + + + + + : Specifiy a settings password. + + + + + + : Specify a file containing + the settings password. @@ -289,7 +288,7 @@ settings password is specified, this information is stored in plain text. After using the - --settingspw|--settingspwfile - option once, it must be always used. Otherwise, the encrypted - setting cannot be unencrypted. + option once, it + must be always used. Otherwise, the encrypted setting cannot be + unencrypted. @@ -318,8 +317,7 @@ registered with &product-name;. By default this displays a compact list with each VM's name and UUID. If you also specify - --long or - -l, this will be a detailed - list as with the showvminfo command, see - . + or , this will be a + detailed list as with the showvminfo + command, see . @@ -527,7 +525,7 @@ - Use the --machinereadable option - to produce the same output, but in machine readable format with a - property=value string on each line. For example: + Use the option to produce the + same output, but in machine readable format with a property=value + string on each line. For example: @@ -623,9 +621,9 @@ name. This name is used by default as the file name of the settings file that has the - .xml extension and the machine - folder, which is a subfolder of the - .config/VirtualBox/Machines - folder. Note that the machine folder path name varies based on the - OS type and the &product-name; version. + .xml extension and the machine folder, which + is a subfolder of the + .config/VirtualBox/Machines folder. Note that + the machine folder path name varies based on the OS type and the + &product-name; version. @@ -808,5 +806,7 @@ PCI bus address]>: Attaches a specified PCI network controller on the host to a specified PCI bus on - the guest. See . + the guest. + + @@ -817,5 +817,7 @@ address>: Detaches a specified PCI network controller on the host from the attached PCI bus on - the guest. See . + the guest. + + @@ -1147,7 +1149,18 @@ --biospxedebug on|off: - Enables additional debugging output when using the Intel PXE - boot ROM. The output is written to the release log file. See - . + Enables or disables additional debugging output when using + the Intel PXE boot ROM. The output is written to the release + log file. See . + + + + + + --system-uuid-le on|off: + Enables or disables representing the system UUID in little + endian form. The default value is on for + new VMs. For old VMs the setting is off + to keep the content of the DMI/SMBIOS table unchanged, which + can be important for Windows license activation. @@ -1224,7 +1237,8 @@ - --vm-process-priority default|flat|low|normal|high - : Specifies the priority scheme of the VM process - to be used when starting this VM and during VM execution. See + --vm-process-priority + default|flat|low|normal|high: Specifies the + priority scheme of the VM process to be used when starting + this VM and during VM execution. See . @@ -1268,6 +1282,5 @@ (generic). These options correspond to the modes described in - . + . @@ -1276,5 +1289,5 @@ --nictype<1-N> - Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio: + Am79C970A|Am79C973|Am79C970|82540EM|82543GC|82545EM|virtio: Enables you to specify the networking hardware that &product-name; presents to the guest for a specified VM @@ -1670,5 +1683,5 @@ connect the virtual serial device to it. Note that Windows requires that the name of a named pipe begins - with \\.\pipe\. + with \\.\pipe\. @@ -1729,7 +1742,6 @@ port such as COM1. On a Linux host, the device name will be - /dev/ttyS0 or similar. - This enables you to wire up a real serial port to a - virtual machine. + /dev/ttyS0 or similar. This enables + you to wire up a real serial port to a virtual machine. @@ -1741,5 +1753,5 @@ uarttype <1-N> - 16450|16550A|16750: Confgures the UART + 16450|16550A|16750: Configures the UART type for a virtual serial port. The default UART type is 16550A. @@ -1831,7 +1843,7 @@ --clipboard-file-transfers - enabled|disabled: - Specifies if clipboard file transfers are allowed between host and - guest OSEs or not. + enabled|disabled: Specifies if clipboard + file transfers are allowed between host and guest OSes or + not. @@ -2652,5 +2664,5 @@ - This command import one or more virtual machines to + This command imports one or more virtual machines into &product-name;. You can import from either of the following: @@ -2666,5 +2678,6 @@ - A cloud service, such as &oci;. Only a single cloud instance can be imported. + A cloud service, such as &oci;. Only a single cloud instance + can be imported. @@ -2673,5 +2686,5 @@ - See for more details on importing VMs from + See for more details on importing VMs into &product-name;. @@ -2684,8 +2697,8 @@ The import subcommand takes at least the path name of an OVF file as input and expects the disk images, if - needed, in the same directory as the OVF file. A lot of additional - command-line options are supported to control in detail what is - being imported and modify the import parameters, but the details - depend on the content of the OVF file. + needed, to be in the same directory as the OVF file. Many + additional command-line options are supported. These enable you + to control in detail what is being imported and to modify the + import parameters, depending on the content of the OVF file. @@ -2694,8 +2707,8 @@ import subcommand with the --dry-run or - -n option. This will then print a - description of the appliance's contents to the screen how it would - be imported into &product-name;, together with the optional - command-line options to influence the import behavior. + -n option. This will then print + a description of the appliance's contents to the screen how it + would be imported into &product-name;, together with the + optional command-line options to influence the import behavior. @@ -2703,14 +2716,14 @@ Use of the --options keepallmacs|keepnatmacs|keepdisknames option - enables additional fine tuning of the clone operation. The first - two options enable specification of how the MAC addresses of every - virtual network card should be handled. They can either be + enables additional fine tuning of the import operation. The + first two options enable you to specify how the MAC addresses of + every virtual network card should be handled. They can either be reinitialized, which is the default setting, left unchanged (keepallmacs) or left unchanged when the network type is NAT (keepnatmacs). If you add - keepdisknames all new disk images - are assigned the same names as the originals, otherwise they are - renamed. + keepdisknames all new disk + images are assigned the same names as the originals, otherwise + they are renamed. @@ -2720,5 +2733,5 @@ - VBoxManage import WindowsXp.ovf --dry-run +VBoxManage import WindowsXp.ovf --dry-run Interpreting WindowsXp.ovf... OK. @@ -2758,131 +2771,191 @@ - The individual configuration items are numbered, and depending on - their type support different command-line options. The import + The individual configuration items are numbered, and depending + on their type support different command-line options. The import subcommand can be directed to ignore many such items with a --vsys X --unit Y --ignore - option, where X is the number of the virtual system and Y the item - number, as printed on the screen. X is zero, unless there are - several virtual system descriptions in the appliance. + option, where X is the number of the virtual system and Y the + item number, as printed on the screen. X is zero, unless there + are several virtual system descriptions in the appliance. In the above example, Item #1 specifies the name of the target - machine in &product-name;. Items #9 and #10 specify hard disk - controllers, respectively. Item #11 describes a hard disk image. + machine in &product-name;. Items #12 and #13 specify hard disk + controllers, respectively. Item #14 describes a hard disk image. In this case, the additional --controller option indicates - which item the disk image should be connected to, with the default - coming from the OVF file. + which item the disk image should be connected to, with the + default coming from the OVF file. - You can combine several items for the same virtual system behind - the same --vsys option. For - example, to import a machine as described in the OVF, but without - the sound card and without the USB controller, and with the disk + You can combine several items for the same virtual system using + the --vsys option. For example, + to import a machine as described in the OVF, but without the + sound card and without the USB controller, and with the disk image connected to the IDE controller instead of the SCSI controller, use the following command: - VBoxManage import WindowsXp.ovf - --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10 +VBoxManage import WindowsXp.ovf + --vsys 0 --unit 8 --ignore --unit 9 --ignore --unit 14 --controller 13 + + Import from &oci; + - As the result of operation a file with the suffix “.oci” will be downloaded on the local host. - This file is a TAR archive which contains a bootable instance image in QCOW2 format and a JSON file with some metadata - related to the imported instance. The downloaded file is deleted after successful import. If import fails the VBoxSVC log file - may hint a name and place where the downloaded file was stored (in case of failure the file may not be deleted). - During import the bootable image is extracted from the archive and converted into VMDK format. The JSON file is also extracted - and stored in the VM folder. + As the result of this operation, a file with the suffix + .oci is downloaded to the local host. This + file is a TAR archive which contains a bootable instance image + in QCOW2 format and a JSON file with some metadata related to + the imported instance. + - The command syntax begins from the "VBoxManage import OCI:// --cloud". + The downloaded file is deleted after a successful import. If + import fails, the downloaded file may not be deleted and the + VBoxSVC log file may indicate the location where the file was + stored. + - List the machines and their ids from Oracle Cloud Infrastructure using the command "VBoxManage cloud --provider=OCI - --profile="your profile name" list instances". + During import the bootable image is extracted from the archive + and converted into VMDK format. The JSON file is also extracted + and stored in the VM machine folder. + - To import a VM from a cloud service such as Oracle Cloud Infrastructure, use the option to specify the - import from the Cloud. Some of the following options are settings for the VM. Somewhere you must enter an Oracle Cloud Identifier (OCID) - for a resource. Use the Oracle Cloud Infrastructure Console to view OCIDs. + The command syntax for importing an &oci; instance begins with + VBoxManage import OCI:// --cloud. + - Next parameters must be followed: - - - - : Specifies new name for imported VM. This name is used as the VM name in VirtualBox. - - - - - : Id of existing instance in the Cloud. - - - - - : Specifies the cloud profile that is used to connect to the cloud service provider. - The cloud profile contains your Oracle Cloud Infrastructure account details, such as your user OCID and the fingerprint for your public key. - To use a cloud profile, you must have the required permissions on Oracle Cloud Infrastructure. - - - - - : Specifies the bucket name in which to store the object created from an instance bootable volume. - In Oracle Cloud Infrastructure, a bucket is a logical container for storing objects. - - - + You can list the available &oci; VM instances and their IDs by + using the following command: + +VBoxManage cloud --provider=OCI --profile=cloud-profile-name list instances + - Some other import options have the same meaning as for OVF import: - - - - : OS type supported by VirtualBox. Use "VBoxManage list ostypes" to see the whole list of supported OSes. - If the type wasn't set the "Unknown" type will be used. - - - - - : folder where new VM will be placed. - - - - - : VM description string. - - - - - : RAM memory assigned for VM in MB. - If memory wasn't set the possible memory size will be deduced from the default memory size for this OS type or will be taken from the cloud instance. - - - - - : Number of virtual CPUs assigned for VM. - If cpus wasn't set the possible number of CPUs will be deduced from the default settings for this OS type or will be taken from the cloud instance. - - - + To import a VM from a cloud service such as &oci;, use the + option to specify the import from the + Cloud. Some of the following options are settings for the VM, + for others you must enter an Oracle Cloud Identifier (OCID) for + a resource. Use the Oracle Cloud Infrastructure Console to view + OCIDs. + - The import options , , , , - are invalid for cloud import. + The following parameters can be specified: + + + + + + : Specifies a new name for the + imported VM. This name is used as the VM name by + &product-name;. + + + + + + : The ID of an existing + instance in the Cloud. + + + + + + : Specifies the cloud profile + that is used to connect to the cloud service provider. The + cloud profile contains your &oci; account details, such as + your user OCID and the fingerprint for your public key. To + use a cloud profile, you must have the required permissions + on &oci;. + + + + + + : Specifies the bucket name in + which to store the object created from an instance bootable + volume. In &oci;, a bucket is a logical container for + storing objects. + + + + + - The following example shows a typical command line for import an instance from Oracle Cloud Infrastructure: + The following import options have the same meaning as for OVF + import: - - # VBoxManage import OCI:// --cloud --vmname import_from_oci --memory 4000 - --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" --cloudinstanceid - ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket - + + + + + + : An OS type supported by + &product-name;. Use the VBoxManage list + ostypes command to see the whole list of supported + OSes. If the type was not set, the + Unknown type is used. + + + + + + : The folder where the new VM + is stored. + + + + + + : A string describing the VM. + + + + + + : The amount of RAM memory assigned + for the VM, in MB. If this option is not set either the + default memory size for the OS type is used, or the value is + taken from the &oci; instance. + + + + + + : the number of virtual CPUs assigned + for the VM. If this option is not set, either the default + virtual CPUs setting for the OS type is used, or the value + is taken from the &oci; instance. + + + + + + + The import options , + , , + , are not + valid for cloud import. + + + + The following example shows a typical command line for importing + an instance from &oci;: + + +# VBoxManage import OCI:// --cloud --vmname import_from_oci --memory 4000 + --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" + --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket @@ -3051,8 +3124,4 @@ permissions on &oci;. - - - Add xref to information about the required permissions. - @@ -3072,5 +3141,5 @@ domain: Specifies the availability domain to use for the VM instance. Enter the - OCID for the availability domain. + full name of the availability domain. @@ -3142,13 +3211,8 @@ - - For the next release, describe exactly what this command does in - terms of the command line options. - - -# VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud ---cloudprofile "standard user" --cloudbucket myBucket ---cloudshape VM.Standard2.1 --clouddomain aaaa:US-ASHBURN-AD-1 --clouddisksize 50 ---cloudocivcn ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet ocid1.subnet.oc1.iad.aaaa... +# VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \ +--cloudprofile "standard user" --cloudbucket myBucket \ +--cloudshape VM.Standard2.1 --clouddomain US-ASHBURN-AD-1 --clouddisksize 50 \ +--cloudocivcn ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet ocid1.subnet.oc1.iad.aaaa... \ --cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true @@ -3375,7 +3439,7 @@ - setlinkstate<1-N> on|off: - Connects or disconnects virtual network cables from their - network interfaces. + setlinkstate<1-N> + on|off: Connects or disconnects virtual + network cables from their network interfaces. @@ -3399,6 +3463,5 @@ (generic). These options correspond to the modes which are described in detail in - . + . @@ -3420,9 +3483,8 @@ trace should be logged. This can be done with the nictracefile<1-N> - <filename> option to VBoxManage - controlvm at runtime or with the - --nictracefile<1-N> - <filename> option to VBoxManage - modifyvm otherwise. + <filename> option to + VBoxManage controlvm at runtime or with the + <filename> option to + VBoxManage modifyvm otherwise. @@ -3541,7 +3603,6 @@ clipboard filetransfers - enabled|disabled: - Specifies if clipboard file transfers are allowed between host and - guest OSEs or not. + enabled|disabled: Specifies if clipboard file + transfers are allowed between host and guest OSes or not. @@ -4053,7 +4114,8 @@ - vm-process-priority default|flat|low|normal|high - : Changes the priority scheme of the VM process. - See . + vm-process-priority + default|flat|low|normal|high: Changes the + priority scheme of the VM process. See + . @@ -4277,7 +4339,6 @@ - If you have a Saved state file - (.sav) that is separate from the - VM configuration, you can use this command to + If you have a Saved state file (.sav) that is + separate from the VM configuration, you can use this command to adopt the file. This will change the VM to saved state and when you start it, &product-name; will attempt to @@ -5313,5 +5374,5 @@ - + VBoxManage modifymedium @@ -5469,5 +5530,5 @@ - + VBoxManage clonemedium @@ -5556,5 +5617,5 @@ clonevdi and clonehd commands are still supported and mapped internally to the - clonehd disk command. + clonemedium command. @@ -5811,5 +5872,5 @@ - This command converts a raw disk image to a &product-name; Disk + This command converts a raw disk image to an &product-name; Disk Image (VDI) file. The syntax is as follows: @@ -5909,5 +5970,5 @@ These commands enable you to attach and retrieve string data for a - virtual machine or for a &product-name; configuration, by + virtual machine or for an &product-name; configuration, by specifying global instead of a virtual machine name. You must specify a keyword as a text string @@ -6088,5 +6149,5 @@ Configures the VBoxSVC release logging details. See - http://www.virtualbox.org/wiki/VBoxLogging. + . @@ -6395,8 +6456,9 @@ the share will be automatically mounted. On Linux distributions, this will be to either - /media/USER/sf_<name> - or /media/sf_<name>, - where <name> is the share named. The actual location - depends on the guest OS. Optional. + /media/USER/sf_share-name + or + /media/sf_share-name, + where share-name is the share + named. The actual location depends on the guest OS. Optional. @@ -6793,5 +6855,5 @@ Specifies the absolute path of the executable on the guest OS file system. Mandatory. For example: - C:\Windows\System32\calc.exe. + C:\Windows\System32\calc.exe. @@ -7073,5 +7135,5 @@ Specifies the absolute path of the executable on the guest OS file system. Mandatory. For example: - C:\Windows\System32\calc.exe + C:\Windows\System32\calc.exe @@ -7315,5 +7377,5 @@ Specifies the absolute path of the host file system destination directory. Mandatory. For example: - C:\Temp. + C:\Temp. @@ -7330,7 +7392,7 @@ Specifies the absolute paths of guest file system files to be copied. Mandatory. For example: - C:\Windows\System32\calc.exe. + C:\Windows\System32\calc.exe. Wildcards can be used in the expressions. For example: - C:\Windows\System*\*.dll. + C:\Windows\System*\*.dll. @@ -7406,5 +7468,5 @@ Specifies the absolute path of the guest file system destination directory. Mandatory. For example: - C:\Temp. + C:\Temp. @@ -7421,7 +7483,7 @@ Specifies the absolute paths of host file system files to be copied. Mandatory. For example: - C:\Windows\System32\calc.exe. + C:\Windows\System32\calc.exe. Wildcards can be used in the expressions. For example: - C:\Windows\System*\*.dll. + C:\Windows\System*\*.dll. @@ -7473,7 +7535,7 @@ For example: If specified directory is - D:\Foo\Bar and - D:\Foo is absent, it - will be created. In such a case, had the + D:\Foo\Bar and + D:\Foo is absent, it will be + created. In such a case, had the --parents option not been used, this command would have failed. @@ -7508,5 +7570,5 @@ Specifies a list of absolute paths of directories to be created on guest file system. Mandatory. For example: - D:\Foo\Bar. + D:\Foo\Bar. @@ -7515,6 +7577,6 @@ switch --parents is used. For example, in the above example - D:\Foo. The specified - user must have sufficient rights to create the specified + D:\Foo. The specified user must + have sufficient rights to create the specified directories, and any parents that need to be created. @@ -7578,7 +7640,7 @@ be deleted on guest file system. Mandatory. Wildcards are allowed. For example: - D:\Foo\*Bar. The - specified user must have sufficient rights to delete the - specified directories. + D:\Foo\*Bar. The specified user + must have sufficient rights to delete the specified + directories. @@ -7641,7 +7703,7 @@ deleted on guest file system. Mandatory. Wildcards are allowed. For example: - D:\Foo\Bar\text*.txt. - The specified user should have sufficient rights to - delete the specified files. + D:\Foo\Bar\text*.txt. The specified + user should have sufficient rights to delete the + specified files. @@ -7862,7 +7924,7 @@ Specifies absolute paths of files or file systems on the guest file system. Mandatory. For example: - /home/foo/a.out. The - specified user should have sufficient rights to access - the specified files or file systems. + /home/foo/a.out. The specified user + should have sufficient rights to access the specified + files or file systems. @@ -9016,5 +9078,5 @@ - - - + + + + + + - + + + - - + + + + + + - + + Index: /trunk/doc/manual/en_US/user_VirtualBoxAPI.xml =================================================================== --- /trunk/doc/manual/en_US/user_VirtualBoxAPI.xml (revision 82349) +++ /trunk/doc/manual/en_US/user_VirtualBoxAPI.xml (revision 82350) @@ -29,5 +29,5 @@ Development Kit (SDK). The SDK is available for download from - http://www.virtualbox.org. + . In particular, the SDK comes with a Programming Guide and Reference manual in PDF format. This manual contains, among other things, the