VirtualBox provides Guest Addition modules for Windows, Linux and Solaris to enable automated logons on the guest.
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.)
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.
To activate the VirtualBox GINA or credential provider module,
install the Guest Additions with using the command line switch
/with_autologon
. All the following
manual steps required for installing these modules will be then done by
the installer.
To manually install the VirtualBox GINA module, extract the Guest
Additions (see Section 4.2.1.4, “Manual file extraction”) and
copy the file VBoxGINA.dll
to the
Windows SYSTEM32
directory. Then, in
the registry, create the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL
with a value of VBoxGINA.dll
.
Note
The VirtualBox GINA module is implemented as a wrapper around
the standard Windows GINA module
(MSGINA.DLL
). As a result, it will
most likely not work correctly with 3rd party GINA modules.
To manually install the VirtualBox credential provider module,
extract the Guest Additions (see Section 4.2.1.4, “Manual file extraction”) and copy the file
VBoxCredProv.dll
to the Windows
SYSTEM32
directory. Then, in the
registry, create the following keys:
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
with all default values (the key named
(Default)
in each key) set to
VBoxCredProv
. After that a new string
named
HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel
with a value of Apartment
has to be
created.
To set credentials, use the following command on a running VM:
VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"
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.
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.
Depending on the particular variant of the Windows guest, the following restrictions apply:
-
For Windows XP guests, 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.
-
For Windows Vista, Windows 7 and Windows 8 guests, the logon 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 (internally, Windows never renames user accounts). -
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
HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon
with a
DWORD
value of1
.
The following command forces VirtualBox to keep the credentials after they were read by the guest and on VM reset:
VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1
Note that this is a potential security risk as a malicious application running on the guest could request this information using the proper interface.
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.
For automated logons on Ubuntu (or Ubuntu-derived) distributions using LightDM as the display manager, please see Section 9.2.2.1, “VirtualBox Greeter for Ubuntu / LightDM”.
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.
Note
The pam_vbox.so
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/
to the security modules directory, usually
/lib/security/
on 32-bit guest Linuxes
or /lib64/security/
on 64-bit ones.
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 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:
-
The
pam_vbox.so
module has to be copied to the security modules directory, in this case it is/lib/security
. -
Edit the PAM configuration file for GDM found at
/etc/pam.d/gdm
, adding the lineauth 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 lineauth requisite pam_vbox.so
. -
If authentication against the shadow database using
pam_unix.so
orpam_unix2.so
is desired, the argumenttry_first_pass
forpam_unix.so
oruse_first_pass
forpam_unix2.so
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/etc/pam.d/common-auth
, to the end of the line referencingpam_unix.so
. This argument tells the PAM module to use credentials already present in the stack, i.e. the ones provided by the VirtualBox PAM module.
Warning
An incorrectly configured PAM stack can effectively prevent you from logging into your guest system!
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.
Note
By default, pam_vbox will not wait for credentials to arrive from the host, in other words: 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.
Starting with VirtualBox 4.1.4 pam_vbox supports various guest
property parameters which all reside 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:
-
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 get deleted no waiting for credentials will be performed and pam_vbox will act like before (see paragraph above). This property must be set read-only for the guest (RDONLYGUEST
). -
CredsWaitAbort
: Aborts waiting for credentials when set to any value. Can be set from host and the guest. -
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
).
To customize pam_vbox further there are the following guest properties:
-
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
). -
CredsMsgWaitTimeout
: Custom message showed when waiting for credentials by pam_vbox timed out, e.g. did not arrive within time. This property must be set read-only for the guest (RDONLYGUEST
).
Note
If a pam_vbox guest property does not have set the right flags
(RDONLYGUEST
) this property will be
ignored then and - depending on the property - a default value will
be set. This can result in pam_vbox not waiting for credentials.
Consult the appropriate syslog file for more information and use the
debug
option.
Starting with version 4.2.12, VirtualBox comes with an own greeter module named vbox-greeter which 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 logons.
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 for the pam_vbox module, vbox-greeter is shipped as part of
the Guest Additions but it is not installed and/or activated on the
guest OS by default For installing vbox-greeter automatically upon
Guest Additions installation, use the
--with-autologon
switch when starting
the VBoxLinuxAdditions.run file:
# ./VBoxLinuxAdditions.run -- --with-autologon
For manual or postponed installation, the
vbox-greeter.desktop
file has to be copied from
/opt/VBoxGuestAdditions-<version>/other/
to the xgreeters
directory, usually
/usr/share/xgreeters/
.
Please refer to your guest OS documentation for the correct LightDM
greeter directory.
The vbox-greeter module itself already was installed by the
VirtualBox 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:
[SeatDefaults] greeter-session=vbox-greeter
Note
The LightDM server needs to be fully restarted in order to
get vbox-greeter used as the default greeter. As root, do a
service lightdm --full-restart
on
Ubuntu, or simply restart the guest.
Note
vbox-greeter is independent of the graphical session chosen by the user (like Gnome, KDE, Unity etc). However, it requires FLTK 1.3 for representing its own user interface.
There are numerous guest properties which can be used to further customize the login experience. For automatically logging in users, the same guest properties apply as for pam_vbox, see Section 9.2.2, “Automated Linux/Unix guest logons”.
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/
:
-
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
: Hexadecimal RRGGBB foreground color for the header text. This property must be set read-only for the guest (RDONLYGUEST
). -
Theme/LogonDialog/BackgroundColor
: Hexadecimal RRGGBB color for the logon dialog background. This property must be set read-only for the guest (RDONLYGUEST
). -
Theme/LogonDialog/ButtonColor
: Hexadecimal RRGGBB background color for the logon dialog button. This property must be set read-only for the guest (RDONLYGUEST
).
Note
The same restrictions for the guest properties above apply as for the ones specified in the pam_vbox section.