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 .

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 is shipped as part of the Guest Additions but it is not installed and/or activated on the guest OS by default. In order to install it, it has to be copied from /opt/VBoxGuestAdditions-version/other/ to the security modules directory. This is usually /lib/security/ on 32-bit Linux guests or /lib64/security/ on 64-bit Linux guests. Please refer to your guest OS documentation for the correct PAM module directory.

For example, to use pam_vbox.so with a Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log in users automatically with the credentials passed by the host, configure the guest OS as follows:

1. Copy the pam_vbox.so module to the security modules directory. In this case, /lib/security.

2. Edit the PAM configuration file for GDM, found at /etc/pam.d/gdm. Add the line auth requisite pam_vbox.so at the top. Additionally, in most Linux distributions there is a file called /etc/pam.d/common-auth. This file is included in many other services, like the GDM file mentioned above. There you also have to add the line auth requisite pam_vbox.so.

3. If authentication against the shadow database using pam_unix.so or pam_unix2.so is desired, the argument try_first_pass for pam_unix.so or use_first_pass for pam_unix2.so is needed in order to pass the credentials from the 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 referencing pam_unix.so. This argument tells the PAM module to use credentials already present in the stack, such as the ones provided by the Oracle VM VirtualBox PAM module.

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.

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