| 1 | <?xml version='1.0' encoding='UTF-8'?>
|
|---|
| 2 | <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
|
|---|
| 3 | <topic xml:lang="en-us" id="autologon_unix">
|
|---|
| 4 | <title>Automated Linux and UNIX Guest Logins</title>
|
|---|
| 5 |
|
|---|
| 6 | <body>
|
|---|
| 7 | <p>
|
|---|
| 8 | <ph conkeyref="vbox-conkeyref-phrases/product-name"/> provides a custom PAM module (Pluggable
|
|---|
| 9 | Authentication Module) which can be used to perform automated
|
|---|
| 10 | guest logins on platforms which support this framework.
|
|---|
| 11 | Virtually all modern Linux and UNIX distributions rely on PAM.
|
|---|
| 12 | </p>
|
|---|
| 13 | <p>
|
|---|
| 14 | For automated logins on Ubuntu, or Ubuntu-derived, distributions
|
|---|
| 15 | using LightDM as the display manager. See
|
|---|
| 16 | <xref href="autologon_unix_lightdm.dita#autologon_unix_lightdm"/>.
|
|---|
| 17 | </p>
|
|---|
| 18 | <p>
|
|---|
| 19 | The <filepath>pam_vbox.so</filepath> module itself
|
|---|
| 20 | <i>does not</i> do an actual verification of the
|
|---|
| 21 | credentials passed to the guest OS. Instead it relies on other
|
|---|
| 22 | modules such as <filepath>pam_unix.so</filepath> or
|
|---|
| 23 | <filepath>pam_unix2.so</filepath> down in the PAM stack to do
|
|---|
| 24 | the actual validation using the credentials retrieved by
|
|---|
| 25 | <filepath>pam_vbox.so</filepath>. Therefore
|
|---|
| 26 | <filepath>pam_vbox.so</filepath> has to be on top of the
|
|---|
| 27 | authentication PAM service list.
|
|---|
| 28 | </p>
|
|---|
| 29 | <note>
|
|---|
| 30 | <p>
|
|---|
| 31 | The <filepath>pam_vbox.so</filepath> module only supports the
|
|---|
| 32 | <codeph>auth</codeph> primitive. Other primitives such as
|
|---|
| 33 | <codeph>account</codeph>, <codeph>session</codeph>, or
|
|---|
| 34 | <codeph>password</codeph> are not supported.
|
|---|
| 35 | </p>
|
|---|
| 36 | </note>
|
|---|
| 37 | <p> The <filepath>pam_vbox.so</filepath> module is shipped as part of the Guest Additions but it
|
|---|
| 38 | is not installed or activated on the guest OS by default. In order to install it, it has to be
|
|---|
| 39 | copied from <filepath>/opt/VBoxGuestAdditions-<varname>version</varname>/other/</filepath> to
|
|---|
| 40 | the security modules directory. This is usually <filepath>/lib/security/</filepath> on 32-bit
|
|---|
| 41 | Linux guests or <filepath>/lib64/security/</filepath> on 64-bit Linux guests. Please refer to
|
|---|
| 42 | your guest OS documentation for the correct PAM module directory. </p>
|
|---|
| 43 | <p>
|
|---|
| 44 | For example, to use <filepath>pam_vbox.so</filepath> with a
|
|---|
| 45 | Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log
|
|---|
| 46 | in users automatically with the credentials passed by the host,
|
|---|
| 47 | configure the guest OS as follows:
|
|---|
| 48 | </p>
|
|---|
| 49 | <ol>
|
|---|
| 50 | <li>
|
|---|
| 51 | <p>
|
|---|
| 52 | Copy the <filepath>pam_vbox.so</filepath> module to the
|
|---|
| 53 | security modules directory. In this case,
|
|---|
| 54 | <filepath>/lib/security</filepath>.
|
|---|
| 55 | </p>
|
|---|
| 56 | </li>
|
|---|
| 57 | <li>
|
|---|
| 58 | <p>
|
|---|
| 59 | Edit the PAM configuration file for GDM, found at
|
|---|
| 60 | <filepath>/etc/pam.d/gdm</filepath>. Add the line
|
|---|
| 61 | <codeph>auth requisite pam_vbox.so</codeph> at the top.
|
|---|
| 62 | Additionally, in most Linux distributions there is a file
|
|---|
| 63 | called <filepath>/etc/pam.d/common-auth</filepath>. This
|
|---|
| 64 | file is included in many other services, like the GDM file
|
|---|
| 65 | mentioned above. There you also have to add the line
|
|---|
| 66 | <codeph>auth requisite pam_vbox.so</codeph>.
|
|---|
| 67 | </p>
|
|---|
| 68 | </li>
|
|---|
| 69 | <li>
|
|---|
| 70 | <p> If authentication against the shadow database using <filepath>pam_unix.so</filepath> or
|
|---|
| 71 | <filepath>pam_unix2.so</filepath> is required, the argument
|
|---|
| 72 | <codeph>try_first_pass</codeph> for <filepath>pam_unix.so</filepath> or
|
|---|
| 73 | <codeph>use_first_pass</codeph> for <filepath>pam_unix2.so</filepath> is needed in order
|
|---|
| 74 | to pass the credentials from the <ph conkeyref="vbox-conkeyref-phrases/product-name"/>
|
|---|
| 75 | module to the shadow database authentication module. For Ubuntu, this must be added to
|
|---|
| 76 | <filepath>/etc/pam.d/common-auth</filepath>, to the end of the line referencing
|
|---|
| 77 | <filepath>pam_unix.so</filepath>. This argument tells the PAM module to use credentials
|
|---|
| 78 | already present in the stack, such as the ones provided by the <ph
|
|---|
| 79 | conkeyref="vbox-conkeyref-phrases/product-name"/> PAM module. </p>
|
|---|
| 80 | </li>
|
|---|
| 81 | </ol>
|
|---|
| 82 | <note type="attention">
|
|---|
| 83 | <p>
|
|---|
| 84 | An incorrectly configured PAM stack can effectively prevent
|
|---|
| 85 | you from logging into your guest system.
|
|---|
| 86 | </p>
|
|---|
| 87 | </note>
|
|---|
| 88 | <p>
|
|---|
| 89 | To make deployment easier, you can pass the argument
|
|---|
| 90 | <codeph>debug</codeph> right after the
|
|---|
| 91 | <filepath>pam_vbox.so</filepath> statement. Debug log output
|
|---|
| 92 | will then be recorded using syslog.
|
|---|
| 93 | </p>
|
|---|
| 94 | <note>
|
|---|
| 95 | <p>
|
|---|
| 96 | By default, <userinput>pam_vbox</userinput> does not wait for
|
|---|
| 97 | credentials to arrive from the host. When a login prompt is
|
|---|
| 98 | shown, for example by GDM/KDM or the text console, and
|
|---|
| 99 | <userinput>pam_vbox</userinput> does not yet have credentials it
|
|---|
| 100 | does not wait until they arrive. Instead the next module in
|
|---|
| 101 | the PAM stack, depending on the PAM configuration, will have
|
|---|
| 102 | the chance for authentication.
|
|---|
| 103 | </p>
|
|---|
| 104 | </note>
|
|---|
| 105 | <p><userinput>pam_vbox</userinput> supports various guest property
|
|---|
| 106 | parameters that are located in
|
|---|
| 107 | <filepath>/VirtualBox/GuestAdd/PAM/</filepath>. These parameters
|
|---|
| 108 | allow <userinput>pam_vbox</userinput> to wait for credentials to be
|
|---|
| 109 | provided by the host and optionally can show a message while
|
|---|
| 110 | waiting for those. The following guest properties can be set:
|
|---|
| 111 | </p>
|
|---|
| 112 | <ul>
|
|---|
| 113 | <li>
|
|---|
| 114 | <p><codeph>CredsWait</codeph>: Set to 1 if
|
|---|
| 115 | <userinput>pam_vbox</userinput> should start waiting until
|
|---|
| 116 | credentials arrive from the host. Until then no other
|
|---|
| 117 | authentication methods such as manually logging in will be
|
|---|
| 118 | available. If this property is empty or gets deleted no
|
|---|
| 119 | waiting for credentials will be performed and
|
|---|
| 120 | <userinput>pam_vbox</userinput> will act like before. This
|
|---|
| 121 | property must be set read-only for the guest
|
|---|
| 122 | (<codeph>RDONLYGUEST</codeph>).
|
|---|
| 123 | </p>
|
|---|
| 124 | </li>
|
|---|
| 125 | <li>
|
|---|
| 126 | <p><codeph>CredsWaitAbort</codeph>: Aborts waiting for
|
|---|
| 127 | credentials when set to any value. Can be set from host and
|
|---|
| 128 | the guest.
|
|---|
| 129 | </p>
|
|---|
| 130 | </li>
|
|---|
| 131 | <li>
|
|---|
| 132 | <p><codeph>CredsWaitTimeout</codeph>: Timeout, in seconds, to
|
|---|
| 133 | let <userinput>pam_vbox</userinput> wait for credentials to
|
|---|
| 134 | arrive. When no credentials arrive within this timeout,
|
|---|
| 135 | authentication of <userinput>pam_vbox</userinput> will be set to
|
|---|
| 136 | failed and the next PAM module in chain will be asked. If
|
|---|
| 137 | this property is not specified, set to 0 or an invalid
|
|---|
| 138 | value, an infinite timeout will be used. This property must
|
|---|
| 139 | be set read-only for the guest
|
|---|
| 140 | (<codeph>RDONLYGUEST</codeph>).
|
|---|
| 141 | </p>
|
|---|
| 142 | </li>
|
|---|
| 143 | </ul>
|
|---|
| 144 | <p>
|
|---|
| 145 | To customize <userinput>pam_vbox</userinput> further there are the
|
|---|
| 146 | following guest properties:
|
|---|
| 147 | </p>
|
|---|
| 148 | <ul>
|
|---|
| 149 | <li>
|
|---|
| 150 | <p><codeph>CredsMsgWaiting</codeph>: Custom message showed
|
|---|
| 151 | while pam_vbox is waiting for credentials from the host.
|
|---|
| 152 | This property must be set read-only for the guest
|
|---|
| 153 | (<codeph>RDONLYGUEST</codeph>).
|
|---|
| 154 | </p>
|
|---|
| 155 | </li>
|
|---|
| 156 | <li>
|
|---|
| 157 | <p><codeph>CredsMsgWaitTimeout</codeph>: Custom message
|
|---|
| 158 | showed when waiting for credentials by
|
|---|
| 159 | <userinput>pam_vbox</userinput> has timed out. For example, they
|
|---|
| 160 | did not arrive within time. This property must be set
|
|---|
| 161 | read-only for the guest (<codeph>RDONLYGUEST</codeph>).
|
|---|
| 162 | </p>
|
|---|
| 163 | </li>
|
|---|
| 164 | </ul>
|
|---|
| 165 | <note>
|
|---|
| 166 | <p>
|
|---|
| 167 | If a <userinput>pam_vbox</userinput> guest property does not have
|
|---|
| 168 | the correct flag set (<codeph>RDONLYGUEST</codeph>) the
|
|---|
| 169 | property is ignored and, depending on the property, a default
|
|---|
| 170 | value will be used. This can result in pam_vbox not waiting
|
|---|
| 171 | for credentials. Consult the appropriate syslog file for more
|
|---|
| 172 | information and use the <codeph>debug</codeph> option.
|
|---|
| 173 | </p>
|
|---|
| 174 | </note>
|
|---|
| 175 | </body>
|
|---|
| 176 | </topic>
|
|---|
