Oracle VM VirtualBox provides Guest Addition modules for Windows, Linux, and Oracle Solaris to enable automated logins on the guest.
When a guest operating system is running in a virtual machine, it might be desirable to perform coordinated and automated logins using credentials from a master login system. Credentials are user name, password, and domain name, where each value might be empty.
Windows provides a modular system login subsystem, called Winlogon, which can be customized and extended by means of so-called GINA (Graphical Identification and Authentication) modules. In Windows Vista and later releases, the GINA modules were replaced with a new mechanism called credential providers. The Oracle VM VirtualBox Guest Additions for Windows come with both, a GINA and a credential provider module, and therefore enable any Windows guest to perform automated logins.
To activate the Oracle VM VirtualBox GINA or credential provider
module, install the Guest Additions using the command line
switch /with_autologon
. All the following
manual steps required for installing these modules will be then
done by the installer.
To manually install the Oracle VM VirtualBox GINA module, extract the
Guest Additions as shown in
Manual File Extraction, and copy the
VBoxGINA.dll
file to the Windows
SYSTEM32
directory. In the registry, create
the following key with a value of
VBoxGINA.dll
:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL
The Oracle VM VirtualBox GINA module is implemented as a wrapper
around the MSGINA.DLL
standard Windows
GINA module. As a result, it might not work correctly with
third-party GINA modules.
To manually install the Oracle VM VirtualBox credential provider
module, extract the Guest Additions as shown in
Manual File Extraction and copy the
VBoxCredProv.dll
file to the Windows
SYSTEM32
directory. 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
All default values, the key named Default
,
must be set to VBoxCredProv
.
Create the following string and assign it a value of
Apartment
.
HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel
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 Oracle VM VirtualBox login modules, GINA or credential provider, using the Oracle VM VirtualBox Guest Additions device driver. When Windows is in logged out mode, the login modules will constantly poll for credentials and if they are present, a login will be attempted. After retrieving the credentials, the login modules will erase them so that the above command will have to be repeated for subsequent logins.
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. 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 Windows guest version, the following restrictions apply:
For Windows XP guests. The login subsystem needs to be configured to use the classic login dialog, as the Oracle VM VirtualBox GINA module does not support the Windows XP-style welcome dialog.
Windows Vista, Windows 7, Windows 8, and Windows 10 guests. The login subsystem does not support the so-called Secure Attention Sequence,
Ctrl+Alt+Del
. As a result, the guest's group policy settings need to be changed to not use the Secure Attention Sequence. Also, the user name given is only compared to the true user name, not the user friendly name. This means that when you rename a user, you still have to supply the original user name as Windows never renames user accounts internally.Automatic login handling of the built-in Windows Remote Desktop Service, formerly known as Terminal Services, is disabled by default. To enable it, create the following registry key with a
DWORD
value of1
.HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon
The following command forces Oracle VM 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.
Oracle VM VirtualBox provides a custom PAM module (Pluggable Authentication Module) which can be used to perform automated guest logins on platforms which support this framework. Virtually all modern Linux and UNIX distributions rely on PAM.
For automated logins on Ubuntu, or Ubuntu-derived, distributions using LightDM as the display manager. See Section 2.1.2.1, “Oracle VM 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.
The pam_vbox.so
module only supports the
auth
primitive. Other primitives such as
account
, session
, or
password
are not supported.
The pam_vbox.so
module is shipped as part
of the Guest Additions but it is not installed and/or activated
on the guest OS by default. In order to install it, it has to be
copied from
/opt/VBoxGuestAdditions-
to the security modules directory. This is usually
version
/other//lib/security/
on 32-bit Linux guests or
/lib64/security/
on 64-bit Linux guests.
Please refer to your guest OS documentation for the correct PAM
module directory.
For example, to use pam_vbox.so
with a
Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log
in users automatically with the credentials passed by the host,
configure the guest OS as follows:
Copy the
pam_vbox.so
module to the security modules directory. In this case,/lib/security
.Edit the PAM configuration file for GDM, found at
/etc/pam.d/gdm
. Add 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 Oracle VM 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, such as the ones provided by the Oracle VM VirtualBox PAM module.
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.
By default, pam_vbox does not wait for credentials to arrive from the host. When a login prompt is shown, for example by GDM/KDM or the text console, and pam_vbox does not yet have credentials it does not wait until they arrive. Instead the next module in the PAM stack, depending on the PAM configuration, will have the chance for authentication.
pam_vbox supports various guest property
parameters that are located in
/VirtualBox/GuestAdd/PAM/
. These parameters
allow pam_vbox to wait for credentials to be
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 gets deleted no waiting for credentials will be performed and pam_vbox will act like before. This property must be set read-only for the guest (RDONLYGUEST
).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 has timed out. For example, they did not arrive within time. This property must be set read-only for the guest (RDONLYGUEST
).
If a pam_vbox guest property does not have
the correct flag set (RDONLYGUEST
) the
property is ignored and, depending on the property, a default
value will be used. This can result in pam_vbox not waiting
for credentials. Consult the appropriate syslog file for more
information and use the debug
option.
Oracle VM VirtualBox comes with a greeter module, named vbox-greeter, that can be used with LightDM. LightDM is the default display manager for Ubuntu Linux and therefore can also be used for automated guest logins.
vbox-greeter does not need the pam_vbox module described in Section 2.1.2, “Automated Linux and UNIX Guest Logins”in order to function. It comes with its own authentication mechanism provided by LightDM. However, to provide maximum flexibility both modules can be used together on the same guest.
As with the pam_vbox module,
vbox-greeter is shipped as part of the
Guest Additions but it is not installed or activated on the
guest OS by default. To install
vbox-greeter automatically upon Guest
Additions installation, use the
--with-autologon
option when starting the
VBoxLinuxAdditions.run file:
# ./VBoxLinuxAdditions.run -- --with-autologon
For manual or postponed installation, copy the
vbox-greeter.desktop
file from
/opt/VBoxGuestAdditions-<version>/other/
to the xgreeters
directory, which is
usually /usr/share/xgreeters/
. See your
guest OS documentation for the name of the correct LightDM
greeter directory.
The vbox-greeter module is installed by the
Oracle VM VirtualBox Guest Additions installer and is located in
/usr/sbin/
. To enable
vbox-greeter as the standard greeter
module, edit the file
/etc/lightdm/lightdm.conf
as follows:
[SeatDefaults] greeter-session=vbox-greeter
The LightDM server must be fully restarted in order for vbox-greeter to be used as the default greeter. As
root
on Ubuntu, run service lightdm --full-restart or restart the guest.vbox-greeter is independent of the graphical session you choose, such as Gnome, KDE, or Unity. However, vbox-greeter does require FLTK 1.3 or later to implement its own user interface.
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 2.1.2, “Automated Linux and UNIX Guest Logins”.
In addition to the previously mentioned guest properties,
vbox-greeter enables you to further
customize its user interface. The following guest properties
are located in the
/VirtualBox/GuestAdd/Greeter/
directory:
HideRestart
: Set to 1 if vbox-greeter should hide the button to restart the guest. This property must be set read-only for the guest (RDONLYGUEST
).HideShutdown
: Set to 1 if vbox-greeter should hide the button to shutdown the guest. This property must be set read-only for the guest (RDONLYGUEST
).BannerPath
: Path to a.PNG
file to use as a banner image on the top of the greeter. The image size must be 460 x 90 pixels, any bit depth. This property must be set read-only for the guest (RDONLYGUEST
).UseTheming
: Set to 1 for turning on the following theming options. This property must be set read-only for the guest (RDONLYGUEST
).Theme/BackgroundColor
: Hexadecimal RRGGBB color for the background. This property must be set read-only for the guest (RDONLYGUEST
).Theme/LogonDialog/HeaderColor
: Hexadecimal RRGGBB foreground color for the header text. This property must be set read-only for the guest (RDONLYGUEST
).Theme/LogonDialog/BackgroundColor
: Hexadecimal RRGGBB color for the login dialog background. This property must be set read-only for the guest (RDONLYGUEST
).Theme/LogonDialog/ButtonColor
: Hexadecimal RRGGBB background color for the login dialog button. This property must be set read-only for the guest (RDONLYGUEST
).
The same restrictions for the guest properties above apply
as for the ones specified in the pam_vbox
section.