9.2. Automated guest logons

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.)

9.2.1. Automated Windows guest logons

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 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:

  1. 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.

  2. For Windows Vista and Windows 7 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).

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.

9.2.2. Automated Linux/Unix guest logons

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.

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>/lib/VBoxGuestAdditions/ to the security modules directory, usually /lib/security/. 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:

  1. The pam_vbox.so module has to be copied to the security modules directory, in this case it is /lib/security.

  2. Edit the PAM configuration file for GDM found at /etc/pam.d/gdm, adding the line auth requisite pam_vbox.so at the top. Additionaly, 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 add the line auth requisite pam_vbox.so.

  3. If authentication against the shadow database using pam_unix.so or pam_unix2.so is desired, the argument try_first_pass 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 referencing pam_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.

Warning

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.