diff options
Diffstat (limited to 'doc/manual/fr_FR/user_AdvancedTopics.xml')
| -rw-r--r-- | doc/manual/fr_FR/user_AdvancedTopics.xml | 1761 |
1 files changed, 1761 insertions, 0 deletions
diff --git a/doc/manual/fr_FR/user_AdvancedTopics.xml b/doc/manual/fr_FR/user_AdvancedTopics.xml new file mode 100644 index 00000000..99254aac --- /dev/null +++ b/doc/manual/fr_FR/user_AdvancedTopics.xml @@ -0,0 +1,1761 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" +"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<chapter id="AdvancedTopics"> + <title>Advanced topics</title> + + <sect1 id="vboxsdl"> + <title>VBoxSDL, the simplified VM displayer</title> + + <sect2> + <title>Introduction</title> + + <para>VBoxSDL is a simple graphical user interface (GUI) that lacks the + nice point-and-click support which VirtualBox, our main GUI, provides. + VBoxSDL is currently primarily used internally for debugging VirtualBox + and therefore not officially supported. Still, you may find it useful + for environments where the virtual machines are not necessarily + controlled by the same person that uses the virtual machine.<note> + <para>VBoxSDL is not available on the Mac OS X host platform.</para> + </note></para> + + <para>As you can see in the following screenshot, VBoxSDL does indeed + only provide a simple window that contains only the "pure" virtual + machine, without menus or other controls to click upon and no additional + indicators of virtual machine activity:</para> + + <para><mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vbox-sdl.png" + width="10cm" /> + </imageobject> + </mediaobject></para> + + <para>To start a virtual machine with VBoxSDL instead of the VirtualBox + GUI, enter the following on a command line:<screen>VBoxSDL --startvm <vm></screen></para> + + <para>where <computeroutput><vm></computeroutput> is, as usual + with VirtualBox command line parameters, the name or UUID of an existing + virtual machine.</para> + </sect2> + + <sect2> + <title>Secure labeling with VBoxSDL</title> + + <para>When running guest operating systems in fullscreen mode, the guest + operating system usually has control over the whole screen. This could + present a security risk as the guest operating system might fool the + user into thinking that it is either a different system (which might + have a higher security level) or it might present messages on the screen + that appear to stem from the host operating system.</para> + + <para>In order to protect the user against the above mentioned security + risks, the secure labeling feature has been developed. Secure labeling + is currently available only for VBoxSDL. When enabled, a portion of the + display area is reserved for a label in which a user defined message is + displayed. The label height in set to 20 pixels in VBoxSDL. The label + font color and background color can be optionally set as hexadecimal RGB + color values. The following syntax is used to enable secure + labeling:</para> + + <screen>VBoxSDL --startvm "VM name" + --securelabel --seclabelfnt ~/fonts/arial.ttf + --seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF</screen> + + <para>In addition to enabling secure labeling, a TrueType font has to be + supplied. To use another font size than 12 point use the parameter + <computeroutput>--seclabelsiz</computeroutput>.</para> + + <para>The label text can be set with <screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen> + Changing this label will take effect immediately.</para> + + <para>Typically, full screen resolutions are limited to certain + "standard" geometries such as 1024 x 768. Increasing this by twenty + lines is not usually feasible, so in most cases, VBoxSDL will chose the + next higher resolution, e.g. 1280 x 1024 and the guest's screen will not + cover the whole display surface. If VBoxSDL is unable to choose a higher + resolution, the secure label will be painted on top of the guest's + screen surface. In order to address the problem of the bottom part of + the guest screen being hidden, VBoxSDL can provide custom video modes to + the guest that are reduced by the height of the label. For Windows + guests and recent Solaris and Linux guests, the VirtualBox Guest + Additions automatically provide the reduced video modes. Additionally, + the VESA BIOS has been adjusted to duplicate its standard mode table + with adjusted resolutions. The adjusted mode IDs can be calculated using + the following formula:</para> + + <screen>reduced_modeid = modeid + 0x30</screen> + + <para>For example, in order to start Linux with 1024 x 748 x 16, the + standard mode 0x117 (1024 x 768 x 16) is used as a base. The Linux video + mode kernel parameter can then be calculated using:</para> + + <screen>vga = 0x200 | 0x117 + 0x30 +vga = 839</screen> + + <para>The reason for duplicating the standard modes instead of only + supplying the adjusted modes is that most guest operating systems + require the standard VESA modes to be fixed and refuse to start with + different modes.</para> + + <para>When using the X.org VESA driver, custom modelines have to be + calculated and added to the configuration (usually in + <literal>/etc/X11/xorg.conf</literal>. A handy tool to determine + modeline entries can be found at <literal><ulink + url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink></literal>.)</para> + </sect2> + + <sect2> + <title>Releasing modifiers with VBoxSDL on Linux</title> + + <para>When switching from a X virtual terminal (VT) to another VT using + Ctrl-Alt-Fx while the VBoxSDL window has the input focus, the guest will + receive Ctrl and Alt keypress events without receiving the corresponding + key release events. This is an architectural limitation of Linux. In + order to reset the modifier keys, it is possible to send + <computeroutput>SIGUSR1</computeroutput> to the VBoxSDL main thread + (first entry in the <computeroutput>ps</computeroutput> list). For + example, when switching away to another VT and saving the virtual + machine from this terminal, the following sequence can be used to make + sure the VM is not saved with stuck modifiers:</para> + + <para><screen>kill -usr1 <pid> +VBoxManage controlvm "Windows 2000" savestate</screen></para> + </sect2> + </sect1> + + <sect1> + <title id="autologon">Automated guest logons</title> + + <para>VirtualBox provides Guest Addition modules for Windows, Linux and + Solaris to enable automated logons on the guest.</para> + + <para>When a guest operating system is running in a virtual machine, it + might be desirable to perform coordinated and automated logons using + credentials from a master logon system. (With "credentials", we are + referring to logon information consisting of user name, password and + domain name, where each value might be empty.)</para> + + <sect2 id="autologon_win"> + <title>Automated Windows guest logons</title> + + <para>Since Windows NT, Windows has provided a modular system logon + subsystem ("Winlogon") which can be customized and extended by means of + so-called GINA modules (Graphical Identification and Authentication). + With Windows Vista and Windows 7, the GINA modules were replaced with a + new mechanism called "credential providers". The VirtualBox Guest + Additions for Windows come with both, a GINA and a credential provider + module, and therefore enable any Windows guest to perform automated + logons.</para> + + <para>To activate the VirtualBox GINA or credential provider module, + install the Guest Additions with using the command line switch + <computeroutput>/with_autologon</computeroutput>. All the following + manual steps required for installing these modules will be then done by + the installer.</para> + + <para>To manually install the VirtualBox GINA module, extract the Guest + Additions (see <xref linkend="windows-guest-file-extraction" />) and + copy the file <computeroutput>VBoxGINA.dll</computeroutput> to the + Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, in + the registry, create the following key: <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen> + with a value of <computeroutput>VBoxGINA.dll</computeroutput>.</para> + + <note> + <para>The VirtualBox GINA module is implemented as a wrapper around + the standard Windows GINA module + (<computeroutput>MSGINA.DLL</computeroutput>). As a result, it will + most likely not work correctly with 3rd party GINA modules.</para> + </note> + + <para>To manually install the VirtualBox credential provider module, extract the + Guest Additions (see <xref linkend="windows-guest-file-extraction" />) + and copy the file <computeroutput>VBoxCredProv.dll</computeroutput> to + the Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, + in the registry, create the following keys:<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ + Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B} + +HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B} + +HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen></para> + + <para>with all default values (the key named + <computeroutput>(Default)</computeroutput> in each key) set to + <computeroutput>VBoxCredProv</computeroutput>. After that a new string + named <screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen> + with a value of <computeroutput>Apartment</computeroutput> has to be + created.</para> + + <para>To set credentials, use the following command on a + <emphasis>running</emphasis> VM:</para> + + <screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen> + + <para>While the VM is running, the credentials can be queried by the + VirtualBox logon modules (GINA or credential provider) using the + VirtualBox Guest Additions device driver. When Windows is in "logged + out" mode, the logon modules will constantly poll for credentials and if + they are present, a logon will be attempted. After retrieving the + credentials, the logon modules will erase them so that the above command + will have to be repeated for subsequent logons.</para> + + <para>For security reasons, credentials are not stored in any persistent + manner and will be lost when the VM is reset. Also, the credentials are + "write-only", i.e. there is no way to retrieve the credentials from the + host side. Credentials can be reset from the host side by setting empty + values.</para> + + <para>Depending on the particular variant of the Windows guest, the + following restrictions apply: <orderedlist> + <listitem> + <para>For <emphasis role="bold">Windows XP guests,</emphasis> the + logon subsystem needs to be configured to use the classic logon + dialog as the VirtualBox GINA module does not support the XP-style + welcome dialog.</para> + </listitem> + + <listitem> + <para>For <emphasis role="bold">Windows Vista and Windows 7 + guests,</emphasis> the logon subsystem does not support the + so-called Secure Attention Sequence + (<computeroutput>CTRL+ALT+DEL</computeroutput>). 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 (internally, Windows never renames user + accounts).</para> + </listitem> + + <listitem> + <para>Auto-logon handling of the built-in Windows Remote Desktop Service + (formerly known as Terminal Services) is disabled by default. To enable + it, create the registry key + <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen> + with a <computeroutput>DWORD</computeroutput> value of <computeroutput>1</computeroutput>.</para> + </listitem> + </orderedlist></para> + + <para>The following command forces VirtualBox to keep the credentials + after they were read by the guest and on VM reset: <screen>VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>Note + that this is a potential security risk as a malicious application + running on the guest could request this information using the proper + interface.</para> + </sect2> + + <sect2 id="autologon_unix"> + <title>Automated Linux/Unix guest logons</title> + + <para>Starting with version 3.2, VirtualBox provides a custom PAM module + (Pluggable Authentication Module) which can be used to perform automated + guest logons on platforms which support this framework. Virtually all + modern Linux/Unix distributions rely on PAM.</para> + + <para>The <computeroutput>pam_vbox.so</computeroutput> module itself + <emphasis role="bold">does not</emphasis> do an actual verification of + the credentials passed to the guest OS; instead it relies on other + modules such as <computeroutput>pam_unix.so</computeroutput> or + <computeroutput>pam_unix2.so</computeroutput> down in the PAM stack to + do the actual validation using the credentials retrieved by + <computeroutput>pam_vbox.so</computeroutput>. Therefore + <computeroutput>pam_vbox.so</computeroutput> has to be on top of the + authentication PAM service list.</para> + + <note> + <para>The <computeroutput>pam_vbox.so</computeroutput> only supports + the <computeroutput>auth</computeroutput> primitive. Other primitives + such as <computeroutput>account</computeroutput>, + <computeroutput>session</computeroutput> or + <computeroutput>password</computeroutput> are not supported.</para> + </note> + + <para>The <computeroutput>pam_vbox.so</computeroutput> 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 + <computeroutput>/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions/</computeroutput> + to the security modules directory, usually + <computeroutput>/lib/security/</computeroutput> on 32-bit guest Linuxes or + <computeroutput>/lib64/security/</computeroutput> on 64-bit ones. Please refer to your + guest OS documentation for the correct PAM module directory.</para> + + <para>For example, to use <computeroutput>pam_vbox.so</computeroutput> + with a Ubuntu Linux guest OS and GDM (the GNOME Desktop Manager) to + logon users automatically with the credentials passed by the host, the + guest OS has to be configured like the following:</para> + + <orderedlist> + <listitem> + <para>The <computeroutput>pam_vbox.so</computeroutput> module has to + be copied to the security modules directory, in this case it is + <computeroutput>/lib/security</computeroutput>.</para> + </listitem> + + <listitem> + <para>Edit the PAM configuration file for GDM found at + <computeroutput>/etc/pam.d/gdm</computeroutput>, adding the line + <computeroutput>auth requisite pam_vbox.so</computeroutput> at the + top. Additionaly, in most Linux distributions there is a file called + <computeroutput>/etc/pam.d/common-auth</computeroutput>. This file + is included in many other services (like the GDM file mentioned + above). There you also have to add the line <computeroutput>auth + requisite pam_vbox.so</computeroutput>.</para> + </listitem> + + <listitem> + <para>If authentication against the shadow database using + <computeroutput>pam_unix.so</computeroutput> or + <computeroutput>pam_unix2.so</computeroutput> is desired, the + argument <computeroutput>try_first_pass</computeroutput> for + <computeroutput>pam_unix.so</computeroutput> or + <computeroutput>use_first_pass</computeroutput> for + <computeroutput>pam_unix2.so</computeroutput> is needed + in order to pass the credentials from the VirtualBox module to the + shadow database authentication module. For Ubuntu, this needs to be + added to <computeroutput>/etc/pam.d/common-auth</computeroutput>, to + the end of the line referencing + <computeroutput>pam_unix.so</computeroutput>. This argument tells + the PAM module to use credentials already present in the stack, i.e. + the ones provided by the VirtualBox PAM module.</para> + </listitem> + </orderedlist> + + <para><warning> + <para>An incorrectly configured PAM stack can effectively prevent + you from logging into your guest system!</para> + </warning></para> + + <para>To make deployment easier, you can pass the argument + <computeroutput>debug</computeroutput> right after the + <computeroutput>pam_vbox.so</computeroutput> statement. Debug log output + will then be recorded using syslog.</para> + + <para><warning> + <para>At present, the GDM display manager only retrieves credentials + at startup so unless the credentials have been supplied to the guest + before GDM starts, automatic logon will not work. This limitation + needs to be addressed by the GDM developers or another display + manager must be used.</para> + </warning></para> + </sect2> + </sect1> + + <sect1> + <title>Advanced configuration for Windows guests</title> + + <sect2 id="sysprep"> + <title>Automated Windows system preparation</title> + + <para>Beginning with Windows NT 4.0, Microsoft offers a "system + preparation" tool (in short: 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 + <computeroutput>sysprep.exe</computeroutput> which is invoked by the + user to put the Windows installation into preparation mode.</para> + + <para>Starting with VirtualBox 3.2.2, the Guest Additions offer a way to + launch a system preparation on the guest operating system in an + automated way, controlled from the host system. To achieve that, see + <xref linkend="guestadd-guestcontrol" /> for using the feature with the + special identifier <computeroutput>sysprep</computeroutput> as the + program to execute, along with the user name + <computeroutput>sysprep</computeroutput> and password + <computeroutput>sysprep</computeroutput> for the credentials. Sysprep + then gets launched with the required system rights.</para> + + <note> + <para>Specifying the location of "sysprep.exe" is <emphasis + role="bold">not possible</emphasis> -- instead the following paths are + used (based on the operating system): <itemizedlist> + <listitem> + <para><computeroutput>C:\sysprep\sysprep.exe</computeroutput> + for Windows NT 4.0, 2000 and XP</para> + </listitem> + + <listitem> + <para><computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput> + for Windows Vista, 2008 Server and 7</para> + </listitem> + </itemizedlist> The Guest Additions will automatically use the + appropriate path to execute the system preparation tool.</para> + </note> + </sect2> + </sect1> + + <sect1> + <title>Advanced configuration for Linux and Solaris guests</title> + + <sect2> + <title>Manual setup of selected guest services on Linux</title> + + <para>The VirtualBox 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:</para> + + <screen> sh ./VBoxLinuxAdditions.run no_setup</screen> + + <para>After this, you will need to at least compile the kernel modules + by running the command <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen> + as root (you will need to replace <emphasis>lib</emphasis> by + <emphasis>lib64</emphasis> on some 64bit guests), and on older guests + without the udev service you will need to add the + <emphasis>vboxadd</emphasis> service to the default runlevel to ensure + that the modules get loaded.</para> + + <para>To setup the time synchronization service, run the command + <screen> /usr/lib/VBoxGuestAdditions/vboxadd-service setup</screen> + and add the service vboxadd-service to the default runlevel. To set up + the X11 and OpenGL part of the Guest Additions, run the command + <screen> /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup</screen> (you + do not need to enable any services for this).</para> + + <para>To recompile the guest kernel modules, use this command: + <screen> /usr/lib/VBoxGuestAdditions/vboxadd setup</screen> After + compilation you should reboot your guest to ensure that the new + modules are actually used.</para> + </sect2> + + <sect2 id="guestxorgsetup"> + <title>Guest graphics and mouse driver setup in depth</title> + + <para>This section assumes that you are familiar with configuring + the X.Org server using xorg.conf and optionally the newer mechanisms + using hal or udev and xorg.conf.d. If not you can learn about + them by studying the documentation which comes with X.Org.</para> + + <para>The VirtualBox Guest Additions come with drivers for X.Org + versions + <itemizedlist> + <listitem>X11R6.8/X11R6.9 and XFree86 version 4.3 + (vboxvideo_drv_68.o and vboxmouse_drv_68.o)</listitem> + <listitem>X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so) + </listitem> + <listitem>X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so) + </listitem> + <listitem>X.Org Server versions 1.3 and later (vboxvideo_drv_13.so + and vboxmouse_drv_13.so and so on).</listitem> + </itemizedlist> + By default these drivers can be found in the directory</para> + <para> + <computeroutput>/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions</computeroutput> + </para> + <para>and the correct versions for the X server are symbolically linked + into the X.Org driver directories.</para> + + <para>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 VirtualBox) and 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.</para> + + <para>The VirtualBox guest graphics driver can use any graphics + configuration for which the virtual resolution fits into the virtual + video memory allocated to the virtual machine (minus a small amount + used by the guest driver) as described in + <xref linkend="settings-display" />. 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.</para> + + <para>With pre-1.3 X Servers 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 section shown here has a custom 2048x800 resolution mode added: + </para> + + <screen>Section "Screen" + Identifier "Default Screen" + Device "VirtualBox graphics card" + Monitor "Generic Monitor" + DefaultDepth 24 + SubSection "Display" + Depth 24 + Modes "2048x800" "800x600" "640x480" + EndSubSection +EndSection</screen> + </sect2> + </sect1> + + <sect1 id="cpuhotplug"> + <title>CPU hot-plugging</title> + + <para>With virtual machines running modern server operating systems, + VirtualBox supports CPU hot-plugging.<footnote> + <para>Support for CPU hot-plugging was introduced with VirtualBox + 3.2.</para> + </footnote> Whereas on a physical computer this would mean that a CPU + can be added or removed while the machine is running, VirtualBox supports + adding and removing virtual CPUs while a virtual machine is + running.</para> + + <para>CPU hot-plugging works only with guest operating systems that + support it. So far this applies only to Linux and Windows Server 2008 x64 + Data Center Edition. Windows supports only hot-add while Linux supports + hot-add and hot-remove but to use this feature with more than 8 CPUs a + 64bit Linux guest is required.</para> + + <para>At this time, CPU hot-plugging requires using the VBoxManage + command-line interface. First, hot-plugging needs to be enabled for a + virtual machine:<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen></para> + + <para>After that, the --cpus option specifies the maximum number of CPUs + that the virtual machine can have:<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>When + the VM is off, you can then add and remove virtual CPUs with the modifyvm + --plugcpu and --unplugcpu subcommands, which take the number of the + virtual CPU as a parameter, like this:<screen>VBoxManage modifyvm "VM name" --plugcpu 3 +VBoxManage modifyvm "VM name" --unplugcpu 3</screen>Note that CPU 0 can never + be removed.</para> + + <para>While the VM is running, CPUs can be added with the + <computeroutput>controlvm plugcpu/unplugcpu</computeroutput> commands + instead:<screen>VBoxManage controlvm "VM name" plugcpu 3 +VBoxManage controlvm "VM name" unplugcpu 3</screen></para> + + <para>See <xref linkend="vboxmanage-modifyvm" /> and <xref + linkend="vboxmanage-controlvm" /> for details.</para> + + <para>With Linux guests, the following applies: To prevent ejection while + the CPU is still used it has to be ejected from within the guest before. + The Linux Guest Additions contain a service which receives hot-remove + events and ejects the CPU. Also, after a CPU is added to the VM it is not + automatically used by Linux. The Linux Guest Additions service will take + care of that if installed. If not a CPU can be started with the following + command:<screen>echo 1 > /sys/devices/system/cpu/cpu<id>/online</screen></para> + </sect1> + + <sect1 id="pcipassthrough"> + <title>PCI passthrough</title> + + <para>When running on Linux hosts, with a recent enough kernel (at least version + <computeroutput>2.6.31</computeroutput>) experimental host PCI devices + passthrough is available.<footnote> + <para>Experimental support for PCI passthrough was introduced with VirtualBox + 4.1.</para> + </footnote></para> + + <note><para>The PCI passthrough module is shipped as a VirtualBox extension + package, which must be installed separately. See <xref + linkend="intro-installing" /> for more information.</para> + </note> + + <para>Essentially this feature allows to directly use physical PCI + devices on the host by the guest even if host doesn't have drivers for this + particular device. Both, regular PCI and some PCI Express cards, are + supported. AGP and certain PCI Express cards are not supported at the + moment if they rely on GART (Graphics Address Remapping Table) unit + programming for texture management as it does rather nontrivial + operations with pages remapping interfering with IOMMU. + This limitation may be lifted in future releases.</para> + + <para>To be fully functional, PCI passthrough support in VirtualBox depends upon + an IOMMU hardware unit which is not yet too widely available. If the device uses + bus mastering (i.e. it performs DMA to the OS memory on its + own), then an IOMMU is required, otherwise such DMA transactions may write to + the wrong physical memory address as the device DMA engine is programmed using + a device-specific protocol to perform memory transactions. The IOMMU functions + as translation unit mapping physical memory access requests from the device + using knowledge of the guest physical address to host physical addresses translation + rules.</para> + + <para>Intel's solution for IOMMU is marketed as "Intel Virtualization Technology for + Directed I/O" (VT-d), and AMD's one is called AMD-Vi. So please check if your + motherboard datasheet has appropriate technology. + Even if your hardware doesn't have a IOMMU, certain PCI cards may work + (such as serial PCI adapters), but the guest will show a warning on boot and + the VM execution will terminate if the guest driver will attempt to enable card + bus mastering.</para> + + <para> + It is very common that the BIOS or the host OS disables the IOMMU by default. + So before any attempt to use it please make sure that + <orderedlist> + <listitem> + <para>Your motherboard has an IOMMU unit.</para> + </listitem> + <listitem> + <para>Your CPU supports the IOMMU.</para> + </listitem> + <listitem> + <para>The IOMMU is enabled in the BIOS.</para> + </listitem> + <listitem> + <para>The VM must run with VT-x/AMD-V and nested paging enabled.</para> + </listitem> + <listitem> + <para>Your Linux kernel was compiled with IOMMU support (including DMA + remapping, see <computeroutput>CONFIG_DMAR</computeroutput> kernel + compilation option). The PCI stub driver + (<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required + as well.</para> + </listitem> + <listitem> + <para>Your Linux kernel recognizes and uses the IOMMU unit + (<computeroutput>intel_iommu=on</computeroutput> + boot option could be needed). Search for DMAR and PCI-DMA in kernel boot + log.</para> + </listitem> + </orderedlist> + </para> + + <para>Once you made sure that the host kernel supports the IOMMU, the next step is + to select the PCI card and attach it to the guest. To figure out the list of + available PCI devices, use the <computeroutput>lspci</computeroutput> command. + The output will look like this + <screen> + 01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450] + 01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series] + 02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit Ethernet controller (rev 03) + 03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03) + 03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03) + 06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1) + </screen> + The first column is a PCI address (in format <computeroutput>bus:device.function</computeroutput>). + This address could be used to identify the device for further operations. + For example, to attach a PCI network controller on the system listed above + to the second PCI bus in the guest, as device 5, function 0, use the following command: + <screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen> + To detach same device, use + <screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen> + Please note that both host and guest could freely assign a different PCI address to + the card attached during runtime, so those addresses only apply to the address of + the card at the moment of attachment (host), and during BIOS PCI init (guest). + </para> + + <para>If the virtual machine has a PCI device attached, certain limitations apply: + <orderedlist> + <listitem> + Only PCI cards with non-shared interrupts (such as using MSI on host) are + supported at the moment. + </listitem> + <listitem> + No guest state can be reliably saved/restored (as the internal state of the PCI + card could not be retrieved). + </listitem> + <listitem> + Teleportation (live migration) doesn't work (for the same reason). + </listitem> + <listitem> + No lazy physical memory allocation. The host will preallocate the whole RAM + required for the VM on startup (as we cannot catch physical hardware accesses + to the physical memory). + </listitem> + </orderedlist> + </para> + + </sect1> + + + <sect1> + <title>Advanced display configuration</title> + + <sect2> + <title>Custom VESA resolutions</title> + + <para>Apart from the standard VESA resolutions, the VirtualBox VESA BIOS + allows you to add up to 16 custom video modes which will be reported to + the guest operating system. When using Windows guests with the + VirtualBox Guest Additions, a custom graphics driver will be used + instead of the fallback VESA solution so this information does not + apply.</para> + + <para>Additional video modes can be configured for each VM using the + extra data facility. The extra data key is called + <literal>CustomVideoMode<x></literal> with <literal>x</literal> + 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 example adds a video mode that corresponds to the native + display resolution of many notebook computers:</para> + + <screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen> + + <para>The VESA mode IDs for custom video modes start at + <literal>0x160</literal>. In order to use the above defined custom video + mode, the following command line has be supplied to Linux:</para> + + <screen>vga = 0x200 | 0x160 +vga = 864</screen> + + <para>For guest operating systems with VirtualBox Guest Additions, a + custom video mode can be set using the video mode hint feature.</para> + </sect2> + + <sect2> + <title>Configuring the maximum resolution of guests when using the + graphical frontend</title> + + <para>When guest systems with the Guest Additions installed are started + using the graphical frontend (the normal VirtualBox application), they + will not be allowed to use screen resolutions greater than the host's + screen size unless the user manually resizes them by dragging the + window, switching to fullscreen or 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:</para> + + <screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen> + + <para>will remove all limits on guest resolutions.</para> + + <screen>VBoxManage setextradata global GUI/MaxGuestResolution >width,height<</screen> + + <para>manually specifies a maximum resolution.</para> + + <screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen> + + <para>restores the default settings. Note that these settings apply + globally to all guest systems, not just to a single machine.</para> + </sect2> + + </sect1> + + <sect1> + <title>Advanced storage configuration</title> + + <sect2 id="rawdisk"> + <title>Using a raw host hard disk from a guest</title> + + <para>Starting with version 1.4, as an alternative to using virtual disk + images (as described in detail in <xref linkend="storage" />), + VirtualBox can also present either entire physical hard disks or + selected partitions thereof as virtual disks to virtual machines.</para> + + <para>With VirtualBox, this type of access is called "raw hard disk + access"; it allows a guest operating system 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, i.e. + whether the virtual disk contains all data written before a host OS + crash. Consult your host OS documentation for details on this.</para> + + <para><warning> + <para>Raw hard disk access is for expert users only. Incorrect use + or use of an outdated configuration can lead to <emphasis + role="bold">total loss of data </emphasis>on the physical disk. Most + importantly, <emphasis>do not</emphasis> attempt to boot the + partition with the currently running host operating system in a + guest. This will lead to severe data corruption.</para> + </warning></para> + + <para>Raw hard disk access -- both for entire disks and individual + partitions -- is implemented as part of the VMDK image format support. + As a result, you will need to create a special VMDK image file which + defines where the data will be stored. After creating such a special + VMDK image, you can use it like a regular virtual disk image. For + example, you can use the Virtual Media Manager (<xref linkend="vdis" />) + or <computeroutput>VBoxManage</computeroutput> to assign the image to a + virtual machine.</para> + + <sect3> + <title>Access to entire physical hard disk</title> + + <para>While this variant is the simplest to set up, you must be aware + that this will give a guest operating system direct and full access to + an <emphasis>entire physical disk</emphasis>. If your + <emphasis>host</emphasis> operating system is also booted from this + disk, please take special care to not access the partition from the + guest at all. On the positive side, the physical disk can be + repartitioned in arbitrary ways without having to recreate the image + file that gives access to the raw disk.</para> + + <para>To create an image that represents an entire physical hard disk + (which will not contain any actual data, as this will all be stored on + the physical disk), on a Linux host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk + -rawdisk /dev/sda</screen>This creates the image + <code>/path/to/file.vmdk</code> (must be absolute), and all data will + be read and written from <code>/dev/sda</code>.</para> + + <para>On a Windows host, instead of the above device specification, + use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead + of the above device specification use e.g. <code>/dev/disk1</code>. + Note that on OS X you can only get access to an entire disk if no + volume is mounted from it.</para> + + <para>Creating the image requires read/write access for the given + device. Read/write access is also later needed when using the image + from a virtual machine.</para> + + <para>Just like with regular disk images, this does not automatically + attach the newly created image to a virtual machine. This can be done + with e.g. <screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller" + --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>When + this is done the selected virtual machine will boot from the specified + physical disk.</para> + </sect3> + + <sect3> + <title>Access to individual physical hard disk partitions</title> + + <para>This "raw partition support" is quite similar to the "full hard + disk" access described above. However, in this case, any partitioning + information will be stored inside the VMDK image, so you can e.g. + install a different boot loader in the virtual hard disk without + affecting the host's partitioning information. While the guest will be + able to <emphasis>see</emphasis> all partitions that exist on the + physical disk, access will be filtered in that reading from partitions + for which no access is allowed the partitions will only yield zeroes, + and all writes to them are ignored.</para> + + <para>To create a special image for raw partition support (which will + contain a small amount of data, as already mentioned), on a Linux + host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk + -rawdisk /dev/sda -partitions 1,5</screen></para> + + <para>As you can see, the command is identical to the one for "full + hard disk" access, except for the additional + <computeroutput>-partitions</computeroutput> parameter. This example + would create the image <code>/path/to/file.vmdk</code> (which, again, + must be absolute), and partitions 1 and 5 of <code>/dev/sda</code> + would be made accessible to the guest.</para> + + <para>VirtualBox uses the same partition numbering as your Linux host. + As a result, the numbers given in the above example would refer to the + first primary partition and the first logical drive in the extended + partition, respectively.</para> + + <para>On a Windows host, instead of the above device specification, + use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead + of the above device specification use e.g. <code>/dev/disk1</code>. + 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.</para> + + <para>The numbers for the list of partitions can be taken from the + output of<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>The + output lists the partition types and sizes to give the user enough + information to identify the partitions necessary for the guest.</para> + + <para>Images which give access to individual partitions are specific + to a particular host disk setup. You cannot transfer these images to + another host; also, whenever the host partitioning changes, the image + <emphasis>must be recreated</emphasis>.</para> + + <para>Creating the image requires read/write access for the given + device. Read/write access is also later needed when using the image + from a virtual machine. If this is not feasible, there is a special + variant for raw partition access (currently only available on Linux + hosts) that avoids having to give the current user access to the + entire disk. To set up such an image, use<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk + -rawdisk /dev/sda -partitions 1,5 -relative</screen>When used from a + virtual machine, the image will then refer not to the entire disk, but + only to the individual partitions (in the example + <code>/dev/sda1</code> and <code>/dev/sda5</code>). 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.</para> + + <para>In some configurations it may be necessary to change the MBR + code of the created image, e.g. to replace the Linux boot loader that + is used on the host by another boot loader. This allows e.g. the guest + to boot directly to Windows, while the host boots Linux from the + "same" disk. For this purpose the + <computeroutput>-mbr</computeroutput> 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<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk + -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>The modified + MBR will be stored inside the image, not on the host disk.</para> + + <para>The created image can be attached to a storage controller in + a VM configuration as usual.</para> + </sect3> + </sect2> + + <sect2 id="changevpd"> + <title>Configuring the hard disk vendor product data (VPD)</title> + + <para>VirtualBox reports vendor product data for its virtual hard disks + which consist of hard disk serial number, firmware revision and model + number. These can be changed using the following commands:</para> + + <screen>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"</screen> + + <para>The serial number is a 20 byte alphanumeric string, the firmware + revision an 8 byte alphanumeric string and the model number a 40 byte + alphanumeric string. Instead of "Port0" (referring to the first port), + specify the desired SATA hard disk port.</para> + + <para>The above commands apply to virtual machines with an AHCI (SATA) + controller. The commands for virtual machines with an IDE controller + are:</para> + + <screen>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"</screen> + + <para>For hard disks it's also possible (experimental!) to mark the drive + as having a non-rotational medium with:</para> + + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen> + + <para>Additional three parameters are needed for CD/DVD drives to report + the vendor product data:</para> + + <screen>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"</screen> + + <para>The vendor id is an 8 byte alphanumeric string, the product id an + 16 byte alphanumeric string and the revision a 4 byte alphanumeric + string. Instead of "Port0" (referring to the first port), specify the + desired SATA hard disk port.</para> + </sect2> + + <sect2> + <title id="iscsi-intnet">Accès à des cibles iSCSI à travers le réseau interne</title> + + <para>En tant que fonctionnalité expérimentale, VirtualBox permet l'accès + à une cible iSCSI en exécutant dans une machine virtuelle ce qui est + configuré pour utiliser le mode Réseau interne (comme décrit au <xref + linkend="network_internal" />). Le paramétrage de la machine virtuelle qui + utilise une telle cible iSCSI se fait comme décrit ci-dessous. La seule + différence est que l'adresse IP de la cible doit être spécifiée comme + adresse IP numérique.</para> + + <para>La pile IP qui accède au réseau interne doit être configurée dans la + machine virtuelle qui accède à la cible iSCSI. Vous devez choisir une + adresse IP statique libre et une adresse MAC non utilisée par d'autres + machines virtuelles. Dans l'exemple ci-dessous, adaptez le nom de la + machine virtuelle, l'adresse MAC et la configuration IP et le nom du + réseau interne (« MyIntNet ») selon vos besoins. Vous devez exécuter les + sept commandes suivantes :<screen>VBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/Trusted 1 +VBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f +VBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1 +VBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0 +VBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet +VBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet +VBoxManage setextradata "nom VM" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen></para> + + <para>Enfin, le disque iSCSI doit être enregistré avec l'option + <code>--intnet</code> pour dire à l'initiateur iSCSI d'utiliser le réseau + interne :<screen>VBoxManage addiscsidisk --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen></para> + + <para>L'adresse cible doit être spécifiée en tant qu'adresse IP numérique + vu qu'il n'y a pas de résolution DNS pour le réseau interne.</para> + + <para>La machine virtuelle avec la cible iSCSI devrait être démarrée avant + que la machine qui l'utilise ne soit allumée. Si une machine virtuelle + utilisant un disque iSCSI est démarrée sans que la cible iSCSI ne soit + allumée, cela peut prendre jusqu'à 200 secondes pour détecter cette + situation. La VM échouera pour s'allumer.</para> + </sect2> + </sect1> + + <sect1> + <title>Launching more than 120 VMs on Solaris hosts</title> + + <para>Solaris hosts have a fixed number of IPC semaphores IDs per process + preventing users from starting more than 120 VMs. While trying to launch + more VMs you would be shown a "Cannot create IPC semaphore" error.</para> + + <para>In order to run more VMs, you will need to bump the semaphore ID + limit of the VBoxSVC process. Execute as root the + <computeroutput>prctl</computeroutput> command as shown below. The process + ID of VBoxSVC can be obtained using the + <computeroutput>ps</computeroutput> list command.</para> + + <para><screen>prctl -r -n project.max-sem-ids -v 2048 <pid-of-VBoxSVC></screen></para> + </sect1> + + <sect1> + <title>Legacy commands for using serial ports</title> + + <para>Starting with version 1.4, VirtualBox provided support for virtual + serial ports, which, at the time, was rather complicated to set up with a + sequence of <computeroutput>VBoxManage setextradata</computeroutput> + statements. Since version 1.5, that way of setting up serial ports is no + longer necessary and <emphasis>deprecated.</emphasis> To set up virtual + serial ports, use the methods now described in <xref + linkend="serialports" />.<note> + <para>For backwards compatibility, the old + <computeroutput>setextradata</computeroutput> statements, whose + description is retained below from the old version of the manual, take + <emphasis>precedence</emphasis> over the new way of configuring serial + ports. As a result, if configuring serial ports the new way doesn't + work, make sure the VM in question does not have old configuration + data such as below still active.</para> + </note></para> + + <para>The old sequence of configuring a serial port used the following 6 + commands:</para> + + <screen>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</screen> + + <para>This sets up a serial port in the guest with the default settings + for COM1 (IRQ 4, I/O address 0x3f8) and the + <computeroutput>Location</computeroutput> 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 <computeroutput>\\.\pipe\</computeroutput>. On Linux the + same config settings apply, except that the path name for the + <computeroutput>Location</computeroutput> can be chosen more freely. Local + domain sockets can be placed anywhere, provided the user running + VirtualBox has the permission to create a new file in the directory. The + final command above defines that VirtualBox acts as a server, i.e. it + creates the named pipe itself instead of connecting to an already existing + one.</para> + </sect1> + + <sect1 id="changenat"> + <title>Fine-tuning the VirtualBox NAT engine</title> + + <sect2> + <title>Configuring the address of a NAT network interface</title> + + <para>In NAT mode, the guest network interface is assigned to the IPv4 + range <computeroutput>10.0.x.0/24</computeroutput> by default where + <computeroutput>x</computeroutput> corresponds to the instance of the + NAT interface +2. So <computeroutput>x</computeroutput> is 2 when there + is only one NAT instance active. In that case the guest is assigned to + the address <computeroutput>10.0.2.15</computeroutput>, the gateway is + set to <computeroutput>10.0.2.2</computeroutput> and the name server can + be found at <computeroutput>10.0.2.3</computeroutput>.</para> + + <para>If, for any reason, the NAT network needs to be changed, this can + be achieved with the following command:</para> + + <screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen> + + <para>This command would reserve the network addresses from + <computeroutput>192.168.0.0</computeroutput> to + <computeroutput>192.168.254.254</computeroutput> for the first NAT + network instance of "VM name". The guest IP would be assigned to + <computeroutput>192.168.0.15</computeroutput> and the default gateway + could be found at <computeroutput>192.168.0.2</computeroutput>.</para> + </sect2> + + <sect2 id="nat-adv-tftp"> + <title>Configuring the boot server (next server) of a NAT network + interface</title> + + <para>For network booting in NAT mode, by default VirtualBox uses a + built-in TFTP server at the IP address 10.0.2.3. This default behavior + should work fine for typical remote-booting scenarios. However, it is + possible to change the boot server IP and the location of the boot image + with the following commands: <screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2 +VBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen></para> + </sect2> + + <sect2 id="nat-adv-settings"> + <title>Tuning TCP/IP buffers for NAT</title> + + <para>The VirtualBox NAT stack performance is often determined by its + interaction with the host's TCP/IP stack and the size of several buffers + (<computeroutput>SO_RCVBUF</computeroutput> and + <computeroutput>SO_SNDBUF</computeroutput>). For certain setups users + might want to adjust the buffer size for a better performance. This can + by achieved using the following commands (values are in kilobytes and + can range from 8 to 1024): <screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen> + This example illustrates tuning the NAT settings. The first parameter is + the MTU, then the size of the socket's send buffer and the size of the + socket's receive buffer, the initial size of the TCP send window, and + lastly the initial size of the TCP receive window. Note that specifying + zero means fallback to the default value.</para> + + <para>Each of these buffers has a default size of 64KB and default MTU + is 1500.</para> + </sect2> + + <sect2> + <title>Binding NAT sockets to a specific interface</title> + + <para>By default, VirtualBox's NAT engine will route TCP/IP packets + through the default interface assigned by the host's TCP/IP stack. (The + technical reason for this is that the NAT engine uses sockets for + communication.) If, for some reason, you want to change this behavior, + you can tell the NAT engine to bind to a particular IP address instead. + Use the following command: <screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen></para> + + <para>After this, all outgoing traffic will be sent through the + interface with the IP address 10.45.0.2. Please make sure that this + interface is up and running prior to this assignment.</para> + </sect2> + + <sect2 id="nat-adv-dns"> + <title>Enabling DNS proxy in NAT mode</title> + + <para>The NAT engine by default offers the same DNS servers to the guest + that are configured on the host. In some scenarios, it can be desirable + to hide the DNS server IPs from the guest, for example when this + information can change on the host due to expiring DHCP leases. In this + case, you can tell the NAT engine to act as DNS proxy using the + following command: <screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen></para> + </sect2> + + <sect2 id="nat_host_resolver_proxy"> + <title>Using the host's resolver as a DNS proxy in NAT mode</title> + + <para>For resolving network names, the DHCP server of the NAT engine + offers a list of registered DNS servers of the host. If for some reason + you need to hide this DNS server list and use the host's resolver + settings, thereby forcing the VirtualBox NAT engine to intercept DNS + requests and forward them to host's resolver, use the following command: + <screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen> + Note that this setting is similar to the DNS proxy mode, however whereas + the proxy mode just forwards DNS requests to the appropriate servers, + the resolver mode will interpret the DNS requests and use the host's DNS + API to query the information and return it to the guest.</para> + </sect2> + + <sect2 id="nat-adv-alias"> + <title>Configuring aliasing of the NAT engine</title> + + <para>By default, the NAT core uses aliasing and uses random ports when + generating an alias for a connection. This works well for 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 via the + VBoxManage frontend with the following commands: + <screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen> + and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen> + The first example disables aliasing and switches NAT into transparent + mode, the second example enforces preserving of port values. These modes + can be combined if necessary.</para> + </sect2> + </sect1> + + <sect1 id="changedmi"> + <title>Configuring the BIOS DMI information</title> + + <para>The DMI data VirtualBox provides to guests can be changed for a + specific VM. Use the following commands to configure the DMI BIOS + information:</para> + + <screen>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/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"</screen> + + <para>If a DMI string is not set, the default value of VirtualBox is used. + To set an empty string use + <computeroutput>"<EMPTY>"</computeroutput>.</para> + + <para>Note that in the above list, all quoted parameters (DmiBIOSVendor, + DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be 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 + <computeroutput>VERR_CFGM_NOT_STRING</computeroutput> error. In that case, + use <computeroutput>"string:<value>"</computeroutput>, for instance + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234"</screen></para> + + <para>Changing this information can be necessary to provide the DMI + information of the host to the guest to prevent Windows from asking for a + new product key. On Linux hosts the DMI BIOS information can be obtained + with <screen>dmidecode -t0</screen>and the DMI system information can be + obtained with <screen>dmidecode -t1</screen></para> + </sect1> + + <sect1> + <title>Fine-tuning timers and time synchronization</title> + + <sect2 id="changetscmode"> + <title>Configuring the guest time stamp counter (TSC) to reflect guest + execution</title> + + <para>By default, VirtualBox keeps all sources of time visible to the + guest synchronized to a single time source, the monotonic host time. + This reflects the assumptions of many guest operating systems, which + expect all time sources to reflect "wall clock" time. In special + circumstances it may be useful however to make the TSC (time stamp + counter) in the guest reflect the time actually spent executing the + guest.</para> + + <para>This special TSC handling mode can be enabled on a per-VM basis, + and for best results must be used only in combination with hardware + virtualization. To enable this mode use the following command:</para> + + <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen> + + <para>To revert to the default TSC handling mode use:</para> + + <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen> + + <para>Note that if you use the special TSC handling mode with a guest + operating system which is very strict about the consistency of time + sources you may get a warning or error message about the timing + inconsistency. It may also cause clocks to become unreliable with some + guest operating systems depending on they use the TSC.</para> + </sect2> + + <sect2 id="warpguest"> + <title>Accelerate or slow down the guest clock</title> + + <para>For certain purposes it can be useful to accelerate or to slow + down the (virtual) guest clock. This can be achieved as follows:</para> + + <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen> + + <para>The above example will double the speed of the guest clock + while</para> + + <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen> + + <para>will halve the speed of the guest clock. Note that changing the + rate of the virtual clock can confuse the guest and can even lead to + abnormal guest behavior. For instance, a higher clock rate means shorter + timeouts for virtual devices with the result that a slightly increased + response time of a virtual device due to an increased host load can + cause guest failures. Note further that any time synchronization + mechanism will frequently try to resynchronize the guest clock with the + reference clock (which is the host clock if the VirtualBox Guest + Additions are active). Therefore any time synchronization should be + disabled if the rate of the guest clock is changed as described above + (see <xref linkend="changetimesync" />).</para> + </sect2> + + <sect2 id="changetimesync"> + <title>Tuning the Guest Additions time synchronization + parameters</title> + + <para>The VirtualBox Guest Additions ensure that the guest's system time + is synchronized with the host time. There are several parameters which + can be tuned. The parameters can be set for a specific VM using the + following command:</para> + + <screen>VBoxManage guestproperty set VM_NAME "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen> + + <para>where <computeroutput>PARAMETER</computeroutput> is one of the + following:</para> + + <para><glosslist> + <glossentry> + <glossterm><computeroutput>--timesync-interval</computeroutput></glossterm> + + <glossdef> + <para>Specifies the interval at which to synchronize the time + with the host. The default is 10000 ms (10 seconds).</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>--timesync-min-adjust</computeroutput></glossterm> + + <glossdef> + <para>The minimum absolute drift value measured in milliseconds + to make adjustments for. The default is 1000 ms on OS/2 and 100 + ms elsewhere.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>--timesync-latency-factor</computeroutput></glossterm> + + <glossdef> + <para>The factor to multiply the time query latency with to + calculate the dynamic minimum adjust time. The default is 8 + times, that means in detail: Measure the time it takes to + determine the host time (the guest has to contact the VM host + service which may take some time), multiply this value by 8 and + do an adjustment only if the time difference between host and + guest is bigger than this value. Don't do any time adjustment + otherwise.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>--timesync-max-latency</computeroutput></glossterm> + + <glossdef> + <para>The max host timer query latency to accept. The default is + 250 ms.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>--timesync-set-threshold</computeroutput></glossterm> + + <glossdef> + <para>The absolute drift threshold, given as milliseconds where + to start setting the time instead of trying to smoothly adjust + it. The default is 20 minutes.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>--timesync-set-start</computeroutput></glossterm> + + <glossdef> + <para>Set the time when starting the time sync service.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>--timesync-set-on-restore + 0|1</computeroutput></glossterm> + + <glossdef> + <para>Set the time after the VM was restored from a saved state + when passing 1 as parameter (default). Disable by passing 0. In + the latter case, the time will be adjusted smoothly which can + take a long time.</para> + </glossdef> + </glossentry> + </glosslist></para> + + <para>All these parameters can be specified as command line parameters + to VBoxService as well.</para> + </sect2> + </sect1> + + <sect1 id="vboxbowsolaris11"> + <title>Installing the alternate bridged networking driver on Solaris 11 + hosts</title> + + <para>Starting with VirtualBox 4.1, VirtualBox ships a new network filter + driver that utilizes Solaris 11's Crossbow functionality. By default, this + new driver is installed for Solaris 11 hosts (builds 159 and above) that + has support for it.</para> + + <para>To force installation of the older STREAMS based network filter + driver, execute as root execute the below command before installing the + VirtualBox package:</para> + + <screen>touch /etc/vboxinst_vboxflt</screen> + + <para>To force installation of the Crossbow based network filter + driver, execute as root the below command before installing the VirtualBox + package:</para> + + <screen>touch /etc/vboxinst_vboxbow</screen> + + <para>To check which driver is currently being used by VirtualBox, + execute:</para> + + <screen>modinfo | grep vbox</screen> + + <para>If the output contains "vboxbow", it indicates VirtualBox is using + the Crossbow network filter driver, while the name "vboxflt" indicates + usage of the older STREAMS network filter.</para> + </sect1> + + <sect1 id="vboxbowvnictemplates"> + <title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title> + + <para>VirtualBox supports VNIC (Virtual Network Interface) templates for + configuring VMs over VLANs.<footnote> + <para>Support for Crossbow based bridged networking was introduced + with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para> + </footnote> A VirtualBox VNIC template is a VNIC whose name starts with + "vboxvnic_template".</para> + + <para>Here is an example of how to use a VNIC template to configure a VLAN + for VMs. Create a VirtualBox VNIC template, by executing as root:</para> + + <screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0 +</screen> + + <para>This will create a temporary VNIC over interface "nge0" with the + VLAN ID 23. To create VNIC templates that are persistent across host + reboots, skip the <computeroutput>-t</computeroutput> parameter in the + above command. You may check the current state of links using:</para> + + <para><screen>$ dladm show-link +LINK CLASS MTU STATE BRIDGE OVER +nge0 phys 1500 up -- -- +nge1 phys 1500 down -- -- +vboxvnic_template0 vnic 1500 up -- nge0 + +$ dladm show-vnic +LINK OVER SPEED MACADDRESS MACADDRTYPE VID +vboxvnic_template0 nge0 1000 2:8:20:25:12:75 random 23 +</screen></para> + + <para>Once the VNIC template is created, all VMs that need to be part of + VLAN 23 over the physical interface "nge0" can use the same VNIC template. + This makes managing VMs on VLANs simpler and efficient, as the VLAN + details are not stored as part of every VM's configuration but rather + picked up via the VNIC template which can be modified anytime using + <computeroutput>dladm</computeroutput>. Apart from the VLAN ID, VNIC + templates can be created with additional properties such as bandwidth + limits, CPU fanout etc. Refer to your Solaris network documentation on how + to accomplish this. These additional properties, if any, are also applied + to VMs which use the VNIC template.</para> + </sect1> + + <sect1 id="addhostonlysolaris"> + <title>Configuring multiple host-only network interfaces on Solaris + hosts</title> + + <para>By default VirtualBox provides you with one host-only network + interface. Adding more host-only network interfaces on Solaris hosts + requires manual configuration. Here's how to add two more host-only + network interfaces.</para> + + <para>You first need to stop all running VMs and unplumb all existing + "vboxnet" interfaces. Execute the following commands as root:</para> + + <screen>ifconfig vboxnet0 unplumb</screen> + + <para>Once you make sure all vboxnet interfaces are unplumbed, remove the + driver using:</para> + + <para><screen>rem_drv vboxnet</screen>then edit the file + <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput> + and add a line for the new interfaces:</para> + + <para><screen>name="vboxnet" parent="pseudo" instance=1; +name="vboxnet" parent="pseudo" instance=2;</screen>Add as many of these lines + as required and make sure "instance" number is uniquely incremented. Next + reload the vboxnet driver using:</para> + + <para><screen>add_drv vboxnet</screen>Now plumb all the interfaces using + <computeroutput>ifconfig vboxnetX plumb</computeroutput> (where X can be + 0, 1 or 2 in this case) and once plumbed you can then configure the + interface like any other network interface.</para> + + <para>To make your newly added interfaces' settings persistent across + reboots you will need to edit the files + <computeroutput>/etc/netmasks</computeroutput>, and if you are using NWAM + <computeroutput>/etc/nwam/llp</computeroutput> and add the appropriate + entries to set the netmask and static IP for each of those interfaces. The + VirtualBox installer only updates these configuration files for the one + "vboxnet0" interface it creates by default.</para> + </sect1> + + <sect1 id="solariscodedumper"> + <title>Configuring the VirtualBox CoreDumper on Solaris hosts</title> + + <para>VirtualBox is capable of producing its own core files when things go + wrong and for more extensive debugging. Currently this is only available + on Solaris hosts.</para> + + <para>The VirtualBox CoreDumper can be enabled using the following + command:</para> + + <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen></para> + + <para>You can specify which directory to use for core dumps with this + command:</para> + + <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir <path-to-directory></screen>Make + sure the directory you specify is on a volume with sufficient free space + and that the VirtualBox process has sufficient permissions to write files + to this directory. If you skip this command and don't specify any core + dump directory, the current directory of the VirtualBox executable will be + used (which would most likely fail when writing cores as they are + protected with root permissions). It is recommended you explicity set a + core dump directory.</para> + + <para>You must specify when the VirtualBox CoreDumper should be triggered. + This is done using the following commands:</para> + + <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1 +VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>At + least one of the above two commands will have to be provided if you have + enabled the VirtualBox CoreDumper.</para> + + <para>Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput> + sets up the VM to override the host's core dumping mechanism and in the + event of any crash only the VirtualBox CoreDumper would produce the core + file.</para> + + <para>Setting <computeroutput>CoreDumpLive</computeroutput> sets up the VM + to produce cores whenever the VM receives a + <computeroutput>SIGUSR2</computeroutput> signal. After producing the core + file, the VM will not be terminated and will continue to run. You can then + take cores of the VM process using:</para> + + <para><screen>kill -s SIGUSR2 <VM-process-id></screen></para> + + <para>Core files produced by the VirtualBox CoreDumper are of the form + <computeroutput>core.vb.<ProcessName>.<ProcessID></computeroutput>, + e.g.<computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para> + </sect1> + + <sect1 id="guitweaks"> + <title>Locking down the VirtualBox manager GUI</title> + + <para>There are several advanced customization settings for locking down + the VirtualBox manager, that is, removing some features that the user + should not see.<screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen></para> + + <para>where <computeroutput>OPTION</computeroutput> is one of the + following keywords:<glosslist> + <glossentry> + <glossterm><computeroutput>noSelector</computeroutput></glossterm> + + <glossdef> + <para>Don't allow to start the VirtualBox manager. Trying to do so + will show a window containing a proper error message.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>noMenuBar</computeroutput></glossterm> + + <glossdef> + <para>VM windows will not contain a menu bar.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>noStatusBar</computeroutput></glossterm> + + <glossdef> + <para>VM windows will not contain a status bar.</para> + </glossdef> + </glossentry> + </glosslist></para> + + <para>To disable any GUI customization do <screen>VBoxManage setextradata global GUI/Customizations</screen></para> + + <para>To disable all host key combinations, open the preferences and + change the host key to <emphasis>None</emphasis>. This might be useful + when using VirtualBox in a kiosk mode.</para> + + <para>Furthermore, you can disallow certain actions when terminating a VM. + To disallow specific actions, type:</para> + + <para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para> + + <para>where <computeroutput>OPTION</computeroutput> is one of the + following keywords:<glosslist> + <glossentry> + <glossterm><computeroutput>SaveState</computeroutput></glossterm> + + <glossdef> + <para>Don't allow the user to save the VM state when terminating + the VM.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>Shutdown</computeroutput></glossterm> + + <glossdef> + <para>Don't allow the user to shutdown the VM by sending the ACPI + power-off event to the guest.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>PowerOff</computeroutput></glossterm> + + <glossdef> + <para>Don't allow the user to power off the VM.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>Restore</computeroutput></glossterm> + + <glossdef> + <para>Don't allow the user to return to the last snapshot when + powering off the VM.</para> + </glossdef> + </glossentry> + </glosslist></para> + + <para>Any combination of the above is allowed. If all options are + specified, the VM cannot be shut down at all.</para> + </sect1> + + <sect1 id="vboxwebsrv-daemon"> + <title>Starting the VirtualBox web service automatically</title> + + <para>The VirtualBox web service + (<computeroutput>vboxwebsrv</computeroutput>) is used for controlling + VirtualBox remotely. It is documented in detail in the VirtualBox Software + Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the + client base using this interface is growing, we added start scripts for + the various operation systems we support. The following describes how to + use them. <itemizedlist> + <listitem> + <para>On Mac OS X, launchd is used. An example configuration file + can be found in + <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>. + It can be enabled by changing the + <computeroutput>Disabled</computeroutput> key from + <computeroutput>true</computeroutput> to + <computeroutput>false</computeroutput>. To manually start the + service use the following command: + <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen> + For additional information on how launchd services could be + configured see <literal><ulink + url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink></literal>.</para> + </listitem> + </itemizedlist></para> + </sect1> + + <sect1 id="vboxballoonctrl"> + <title>Memory Ballooning Service</title> + + <para>Starting with VirtualBox 4.0.8 a new host executable called + <computeroutput>VBoxBalloonCtrl</computeroutput> is available to + automatically take care of a VM's configured memory balloon + (see <xref linkend="guestadd-balloon" /> for an introduction to memory + ballooning). This is especially useful for server environments where + VMs may dynamically require more or less memory during runtime.</para> + + <para>VBoxBalloonCtrl periodically checks a VM's current memory balloon + and its free guest RAM and automatically adjusts the current memory + balloon by inflating or deflating it accordingly. This handling only + applies to running VMs having recent Guest Additions installed.</para> + + <para>To set up VBoxBalloonCtrl and adjust the maximum ballooning size a + VM can reach the following parameters will be checked in the following + order: + <itemizedlist> + <listitem>specified via VBoxBalloonCtrl command line parameter + <computeroutput>--balloon-max</computeroutput></listitem> + <listitem>per-VM parameter using + <screen>VBoxManage setextradata "VM-Name" VBoxInternal/Guest/BalloonSizeMax <Size in MB></screen></listitem> + <listitem>global parameter for all VMs using + <screen>VBoxManage setextradata global VBoxInternal/Guest/BalloonSizeMax <Size in MB></screen></listitem> + </itemizedlist> + <note> + <para>If no maximum ballooning size is specified by at least one of the + parameters above, no ballooning will be performed at all.</para> + </note> + </para> + + <para>For more options and parameters check the built-in command line help + accessible with <computeroutput>--help</computeroutput>.</para> + </sect1> + + <sect1 id="autostart"> + <title>Starting virtual machines during system boot</title> + + <para>Starting with VirtualBox 4.2.0 it is possible to start VMs automatically during + system boot on Linux and Mac OS X for all users. </para> + + <sect2 id="autostart-linux"> + <title>Linux: starting the autostart service via <computeroutput>init</computeroutput></title> + + <para>On Linux, the autostart service is activated by setting two variables in + <computeroutput>/etc/default/virtualbox</computeroutput>. + The first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput> 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 <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput> + 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 config file can be placed in <computeroutput>/etc/vbox</computeroutput> + and contains several options. One is <computeroutput>default_policy</computeroutput> + 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 <computeroutput>exception_list</computeroutput> + and contains a comma seperated 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:</para> + + <para><screen> +# Default policy is to deny starting a VM, the other option is "allow". +default_policy = deny +# Users which are allowed are given below. +# If the default policy is to allow starting a VM is not allowed for the users below. +exception_list = bob, alice, joe + +bob = 30 # Bobs machines will be started 30 seconds after the autostart service started +alice = 180 # Alice machines will be started 180 seconds after the autostart service started +joe = 240 # Joes machines will be started 240 seconds after the autostart service started + </screen></para> + + <para>Every user who wants to enable autostart for individual machines + has to set the path to the autostart database directory with + <screen>VBoxManage setproperty autostartdbpath <Autostart directory></screen> + </para> + </sect2> + + <sect2 id="autostart-solaris"> + <title>Solaris: starting the autostart service via SMF</title> + + <para>On Solaris hosts, the VirtualBox 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 <xref linkend="autostart-linux" />): + <screen>svccfg -s svc:/application/virtualbox/autostart:default setprop config/config=/etc/vbox/autostart.cfg</screen> + </para> + + <para>When everything is configured correctly you can start the + VirtualBox autostart service with the following command:<screen>svcadm enable svc:/application/virtualbox/autostart:default</screen></para> + + <para>For more information about SMF, please refer to the Solaris + documentation.</para> + </sect2> + + <sect2 id="autostart-osx"> + <title>Mac OS X: starting the autostart service via launchd</title> + + <para>On Mac OS X, launchd is used to start the VirtualBox autostart service. An + example configuration file can be found in + <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>. + To enable the service copy the file to <computeroutput>/Library/LaunchDaemons</computeroutput> and change the + <computeroutput>Disabled</computeroutput> key from + <computeroutput>true</computeroutput> to + <computeroutput>false</computeroutput>. Furthermore replace the second parameter + to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />). + To manually start the service use the following command: + <screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen> + For additional information on how launchd services could be + configured see <literal><ulink + url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink></literal>.</para> + </sect2> + </sect1> +</chapter> |